Skip to content

perhapsspy/project-legibility / plugins/project-legibility/skills/project-context

project-context

Unverified

Resume, handoff, and long-running repo work by keeping durable context across threads or agents: task briefs, logs, and reusable reference notes.

Project Context

Purpose

Keep durable repo context in ordinary files so later sessions can resume without rebuilding state.

Use this skill for resume, handoff, long-running work, subagent follow-through, reusable reference context, or task logs. Do not bootstrap it for a read-only question or one-shot inspection. If a repo has existing context docs but no project-context layout, choose explicit adoption or use project-context-migration before creating a parallel tree.

Contract

docs/
  reference/**/*.md
  tasks/yyyy/mm-dd/<task-slug>/
    BRIEF.md
    logs/{DECISIONS,WORKLOG}.md
    [optional] <purpose-named-backlog>.md
    [optional] working/
    [optional] archive/
  [optional] BACKLOG.md
  • docs/reference/** owns reusable current rules and reliable facts. Keep investigation history, progress, timelines, code inventories, and provenance narrative out. Point to authoritative code, API, config, test, or project documents instead of restating them. Apply corrections or deletion requests by rewriting or removing stale claims.
  • BRIEF.md is a rewrite-only resume card: stable goal, scope boundary, current conclusions and state, and the nearest restartable step. It is not a report, history, evidence log, file inventory, or backlog. At a phase boundary, rewrite it to the new resume state and move prior evidence or chronology to logs, working/, or archive/.
  • logs/WORKLOG.md records one concise outcome entry per meaningful settled batch, not commands or micro-iterations. logs/DECISIONS.md records only decisions that change future interpretation, scope, architecture, rollback, or rule application. Keep DECISIONS.md empty until there is a decision to record. Let the bundled log helper own exact block shape.
  • A task root contains current-canonical documents and routers. Keep durable human-readable drafts, investigation notes, undecided plans, methods, and compact evidence summaries in working/. Put completed, rejected, replaced, or stale context in archive/.
  • Keep disposable experiment and browser-test code, state, and raw output in an isolated workspace outside the repository, then discard them after inspection. Keep reusable tools and retained evidence with their source, test, or runbook owner; task documents point to them.
  • Use a purpose-named task backlog only when one nearest step is insufficient. Keep inactive repo-level work in docs/BACKLOG.md.

Task Identity and Shared Ownership

  • Reuse a task or session only when the unresolved goal, write scope, and expected output still match. When purpose or completion criteria change, pass the smallest resumable handoff into a new task; keep the active writer unique.
  • Before concurrent repository writes, establish checkout, branch, index, and commit ownership. A clean starting status does not establish exclusive access. Use isolated worktrees/checkouts or serialize shared index and commit operations, and check the staged scope before committing.
  • Changes contributing to the same product release candidate share one integration owner and canonical candidate identity. Reconcile their source revisions and evidence there before promotion; task-local progress alone does not establish a separate candidate.
  • When multiple tasks, owners, or phases depend on an interpretation that changes implementation or acceptance, assign one current canonical owner. Prefer an existing code, API, config, test, or project-document owner. Otherwise use a purpose-named task-root contract for task-specific meaning or docs/reference/** for reusable meaning.
  • Consumers point to that owner and keep only task-specific state, deviations, and next action. Do not mirror the same open work across brief, backlog, working notes, and logs.

Operation and Validation

On task entry, resume, or context loss, read the brief and only the context needed to reconcile the goal, current state, and restart point. During continuous work, reuse available context and refresh only what is missing, affected by changes, or needed for a freshness-sensitive decision. When the current state proves the goal complete, close the selected task and keep adjacent next steps as candidates until the user or an authoritative approved plan selects them.

Reuse the matching unfinished task or create a dated task with the core files; skip creating a new task only for a small, low-judgment change finished immediately. Add optional surfaces only for a distinct owner or reader action.

Assign one writer for the brief and canonical logs. Other agents write them only under an explicit bounded assignment. Use repo-relative paths or stable placeholders, store no secrets, and pass delegated work only the current goal, constraints, unknowns, evidence command, artifact path, and canonical pointers it needs. Bounded subagents start from that handoff, read further context only as needed, and return results, verification evidence, and remaining gaps to the task writer. Create a separate task only when the assignment needs independent resume or handoff.

Proceed with reversible stated assumptions when context is missing; ask before changing authority or making a hard-to-reverse commitment.

Use the bundled log helper and runtime-shape checker; their scripts own exact mechanics. For routine completion or handoff, run the skill-relative scripts/check_runtime_shape.py --task-root docs/tasks/yyyy/mm-dd/<task-slug>; the task path is relative to the detected repo or explicit --repo-root. Omit --task-root for a repository-wide audit or migration check. The checker covers required shape, latest log blocks, portable paths, and secret-like markers, not ownership, semantic quality, full history, or migration correctness. When a task is maintained, finish only when its brief can reopen the work and current context has one clear owner.

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 319kUpdated Claude CodeCodexVerifiedInstall