diff --git a/CONTEXT.md b/CONTEXT.md index aeb424f..d1a506e 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -17,13 +17,11 @@ description: Domain language and decisions for the global AI development config Workflow artifacts are committed to `docs/` in subdirectories by type. All are tracked as issues. **Naming:** -- `docs/prd/.md` — Product Requirements Documents - `docs/notes/.md` — Exploration Notes - `docs/adr/NNNN-.md` — Architecture Decision Records -- `docs/issues/NNNN-.md` — Issues - `docs/spec/.md` — Living spec files (current deployed state); updated in the same PR as any behavior change -**NNNN** — zero-padded 4-digit sequential number (e.g. `0001`, `0042`). Used only for artifact types referenced by number (issues, ADRs). PRDs, ARDs, Bug Briefs, and Notes are referenced by topic and use a descriptive slug only. +**NNNN** — zero-padded 4-digit sequential number (e.g. `0001`, `0042`). Used only for ADRs (referenced by number). Notes, Specs, and other artifacts are referenced by topic and use a descriptive slug only. **Other repo-level artifacts:** - `LESSONS.md` — long-loop feedback log; patterns observed during development. Three or more entries on the same pattern graduate to the relevant standing file. Updated by the session-handoff skill or by the human directly. @@ -105,7 +103,7 @@ A per-skill markdown file containing a single YAML code block with provenance an A third finding level in `skill-audit` reports, below SUGGESTION. Observational — flags something worth noting that is not actionable and does not imply a defect. A skill with only INFO findings is a clean PASS. Counted separately in the result block as `· P info` and never mixed into the FAIL or SUGGESTION counts. Current use: a `references/*.md` file with no `source_keys` when `sources.md` is present; a skill-level source slug not found in the upstream research sources. See ADR-0014. ### Provider-agnostic issue tracker -Skills and workflows reference "linked issue" generically rather than a specific provider. In the file-based phase, an issue is a `docs/issues/NNNN-.md` file. When Gitea MCP is configured, the same skills use it instead. The active backend is determined at runtime by MCP availability. "Issue" is the canonical cross-provider term (GitHub, GitLab, Gitea all use it). +Skills and workflows reference "linked issue" generically rather than a specific provider. Gitea is the canonical issue tracker for this repo (see ADR-0017). "Issue" is the cross-provider term (GitHub, GitLab, Gitea all use it). ### Provenance chain The three-stage traceability record linking a skill back to its research inputs: (1) `/research` produces topic docs and a `sources.md` in `plugins//docs/research/docs//`; (2) `/skill-author` reads those docs and records which sources informed which skill files in `references/sources.md` (including a `Research doc:` back-pointer to the upstream research file) and `source_keys` frontmatter on `SKILL.md` and `references/*.md`; (3) `skill-audit` validates the chain is complete and internally consistent via `validate-provenance.sh`. A skill with research input but no `references/sources.md`, or with `source_keys` that don't match `references/sources.md` slugs, has a broken provenance chain. @@ -122,6 +120,9 @@ Files that reference other files should declare those references explicitly. The ### Workstream A focused work session oriented around a single goal — a feature, bug, improvement, or exploration. Starts with a grill to produce an artifact (PRD, Bug Brief, ADR, etc.), runs through issue implementation, and closes with docs + commit. Ongoing skills (/diagnose, /prototype, /zoom-out) are invoked ad hoc within a workstream as needed. +### LESSONS.md +Long-loop feedback log for patterns observed across sessions. Three or more entries on the same pattern graduate to the relevant standing file (e.g. a coding convention, a governance rule). Updated by the session-handoff skill or directly by the human. Lives at the repo root. + ### Workflow artifacts Output documents produced by a grill session that scope the work before implementation. All are committed to the repo under `docs/` following the docs convention. Each artifact generates one or more issues but is not itself an issue.