--- name: repo-context # must match directory name description: Always load first in this repo to manage PRDs\/specs\/projects and keep append-only Implementation Notes. metadata: workflow: repo-context init: bun .\/context\/skills\/repo-context\/scripts\/init.ts templates: .\/context\/skills\/repo-context\/assets --- ## Always load this skill first - When working in this repository, load `repo-context` at the start of planning\/building work. - Build work requires an active PRD; read it before edits. - Active work selection is user-chosen: suggest up to 3 candidates, never auto-select. - End of planning\/building: update the active PRD and append to **Implementation Notes (Append-only)**. - If `context\/` is missing, offer to initialize via `bun .\/context\/skills\/repo-context\/scripts\/init.ts`. ## Templates - Use the templates in `.\/assets\/` for new docs. - Optional parent references (`projectId`, `initiativeIds`, `specRefs`, `codeAreas`) are marked with YAML comments. ## Reference (verbatim): REPO_CONTEXT_SYSTEM.md # Repo Context System ## Purpose A repo-local context system that mirrors Linear’s structure while staying AI-friendly and compatible with OpenCode’s default tooling. The system prioritizes colocated, comprehensive documentation so PRDs\/specs do not require follow-up questions. ## High-Level Structure Flat folders for fast `glob`\/`read` workflows and minimal path guessing: ``` context\/ README.md specs\/ initiatives\/ projects\/ prds\/ ``` - **Specs**: stable, cross-cutting invariants (data model, planning, verification, standards). - **Initiatives**: outcome-focused containers; multiple active initiatives are allowed. - **Projects**: execution containers with milestones (phases) and PRD links. - **PRDs**: shippable slices; include user stories + implementation notes. PRDs may exist without a project (e.g., small bug fixes). ## Key Rules - **End of planning**: write\/update the active PRD and append Implementation Notes (decisions + next steps). - **End of building**: update story status (`completedAt`, `passes`) and append Implementation Notes (what shipped + verification). - **No separate updates folder**: progress is colocated within PRDs under an append-only Implementation Notes section. - **Completion tracking**: use `completedAt: | null` (no boolean `complete`). - **PRDs must be comprehensive**: include summary, goals\/non-goals, edge cases, verification, and open questions (empty when `status: ready`). ## Atomicity - **Specs are primitives\/invariants**: a spec defines stable invariants. If it becomes execution planning or a backlog, split it or move work into PRDs. - **PRDs are atomic**: one PRD = one shippable slice with clear verification; split if scope expands. ## Suggestion Signals (Non-binding) Used only to suggest candidate work items when the user is unsure; never auto-select. - PRDs: incomplete stories (`completedAt: null`), missing required sections, open questions blocking `ready`, or stalled despite recent `updatedAt`. - Specs: ambiguous\/conflicting invariants, missing verification guidance, or too broad to remain a primitive. ## Skill Name `repo-context` ## Skill Usage Policy (No Hooks) - **Plan agent**: always load the `repo-context` skill at the start; ensure PRD is complete and append Implementation Notes at the end of planning. - **Build agent**: always read the active PRD before edits; update story completion fields and append Implementation Notes at the end of building. ## Active Work Selection (User-Chosen, Agent Suggested) Selection is interactive; the agent never auto-selects. The user chooses the active work item or mode. **Modes** - **Plan**: create or refine a spec \/ initiative \/ project \/ PRD into a concrete plan. - **Build**: implement work against an agreed plan. - **Review**: PR\/code\/architecture review with findings and recommendations. - **Explore**: repo Q&A, discovery, debugging\/triage. **PRD linkage** - Any mode may be linked to a PRD, but only **Build** requires an active PRD. - Only encourage creating\/selecting a PRD once there is a concrete, shippable plan. - If `projectId` is set, derive initiative membership from the project; only use `initiativeIds` for standalone PRDs. **Selection workflow (user-chosen, agent-suggested)** 1. If the user names a work item (`PRD-###`, `context\/prds\/...`, spec\/project\/initiative id\/path), use it. 2. If the user describes work but does not name an item, suggest up to 3 relevant candidates (ranked by fit + PRD frontmatter `updatedAt`), plus a “Create new PRD” option when appropriate, and ask the user to choose. 3. If the user doesn’t know what to work on, suggest candidates and ask 2–4 questions to converge. When suggesting candidates, follow `## Atomicity` and `## Suggestion Signals (Non-binding)`. ## Initiative Template `context\/initiatives\/INIT-001-.md` ```md --- id: INIT-001 title: status: draft # draft | active | paused | done | cancelled owners: - createdAt: 2026-01-19 updatedAt: 2026-01-19 successMetrics: - nonGoals: - specRefs: - context\/specs\/.md --- # INIT-001: ## Summary Why this initiative exists and what “better” looks like. ## User \/ Customer Who benefits and in what scenario(s). ## Success Metrics - - ## Non-goals - - ## Scope Boundaries **In scope** - ... **Out of scope** - ... ## Projects (Derived) Projects in this initiative are `context\/projects\/PROJ-*.md` where frontmatter `initiativeIds` includes `INIT-001`. ## Risks \/ Dependencies - ... ## Open Questions (Keep empty when `status: active`.) - [ ] ... ``` ## Project Template `context\/projects\/PROJ-001-.md` ```md --- id: PROJ-001 title: status: draft # draft | active | paused | done | cancelled initiativeIds: - INIT-001 owners: - createdAt: 2026-01-19 updatedAt: 2026-01-19 codeAreas: - apps\/<...>\/ specRefs: - context\/specs\/.md --- # PROJ-001: ## Summary What this project will deliver (not how). ## Outcome How this project contributes to its initiative success metrics. ## Scope Boundaries **In scope** - ... **Out of scope** - ... ## Milestones (Project Phases) ### M1 — **Exit criteria** - ... ### M2 — **Exit criteria** - ... ## PRDs (Derived) PRDs in this project are `context\/prds\/PRD-*.md` where frontmatter `projectId: PROJ-001`. ## Risks \/ Dependencies - ... ## Verification (Project-level) (Prefer referencing `context\/specs\/verification.md`; only list project-specific checks here.) - ... ``` ## Tightened PRD Template `context\/prds\/PRD-001-.md` ```md --- id: PRD-001 title: status: draft # draft | ready | in_progress | done | cancelled projectId: PROJ-001 # optional branchName: owners: - createdAt: 2026-01-19 updatedAt: 2026-01-19 stories: - id: US-001 title: acceptanceCriteria: - priority: 1 passes: 0 completedAt: null notes: "" --- # PRD-001: ## Summary 1–3 paragraphs describing the user value and the problem being solved. ## Goals - ... ## Non-goals - ... ## Scope Boundaries **In scope** - ... **Out of scope** - ... ## User Stories ### US-001 — (P1) **Acceptance Criteria** - **Notes** - ... ## Edge Cases - ... ## Verification - `bun run typecheck` - `bun run test` ## Open Questions (Must be empty when `status: ready`.) - [ ] ... ## Implementation Notes (Append-only) ### 2026-01-19 **Decisions** - ... **Changes** - ... **Verification** - ... **Follow-ups** - [ ] ... ``` ## Where to Put The Entry Point Use `context\/README.md` as the main index and workflow instructions (not `context\/ROADMAP.md`).