From 893f5406456b275adae3f1ca711e8b567332ec76 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sun, 28 Jun 2026 17:28:52 +0000 Subject: [PATCH] docs(context): align CONTEXT.md with plugin/Gitea model ## Why Part of issue #15 (refactor: align repo with marketplace/plugin model). docs/issues/ and docs/prd/ are gone; Gitea is now the canonical tracker (ADR-0017). LESSONS.md glossary entry needed to survive the upcoming ROADMAP.md slim-down. ## Impact - Docs convention no longer lists docs/prd/ or docs/issues/ naming entries - NNNN explanation scoped to ADRs only - Provider-agnostic issue tracker entry drops file-based-phase language - LESSONS.md has a first-class glossary entry Refs: #15 ADR: docs/adr/0017-gitea-canonical-issue-tracker.md Co-authored-by: Claude Sonnet 4.6 --- CONTEXT.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) 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.