From 067ffdfa544fa6fddd8e6078060e246a2be496fb Mon Sep 17 00:00:00 2001 From: MacAttak Date: Sun, 15 Feb 2026 17:57:28 +1100 Subject: [PATCH 1/8] feat(protocols): add landscape protocol for codebase reference document Defines format, size targets (3000-word cap), freshness rules (7-day default), and update semantics for LANDSCAPE.md. Co-Authored-By: Claude Opus 4.6 --- protocols/landscape.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 protocols/landscape.md diff --git a/protocols/landscape.md b/protocols/landscape.md new file mode 100644 index 0000000..00c15e8 --- /dev/null +++ b/protocols/landscape.md @@ -0,0 +1,33 @@ +# Landscape Protocol + +## Format + +`.specwright/LANDSCAPE.md` is a reference document (not an anchor document). Optional. Never blocks workflow. + +Required metadata header: +``` +Snapshot: {ISO 8601 timestamp} +Files: {count} | Modules: {count} +``` + +Required sections: Architecture, Modules (per-module: purpose, key files, public API, dependencies), Conventions, Integration Points, Gotchas. + +## Size + +- Small projects: 500-1000 words +- Large projects: 1500-2500 words +- Hard cap: 3000 words + +## Freshness + +Parse `Snapshot:` timestamp. Default staleness threshold: 7 days. Configurable via `config.landscape.stalenessThresholdDays` (optional field, default 7). + +- Fresh: use as-is +- Stale: consumer warns user, may refresh inline +- Missing: no warning, proceed without + +## Updates + +- **Full rewrite**: initial generation and refresh (replace entire document) +- **Incremental merge**: post-ship updates (re-scan affected modules only, preserve unchanged sections, update timestamp) +- Module granularity: one section per logical module, package, or top-level directory From a23e5d2148b10a93ab3f56efa1174a2f1a926bc6 Mon Sep 17 00:00:00 2001 From: MacAttak Date: Sun, 15 Feb 2026 17:57:55 +1100 Subject: [PATCH 2/8] feat(protocols): add reference documents section with LANDSCAPE.md Adds LANDSCAPE.md as an optional, load-on-demand reference document separate from anchor documents (Constitution, Charter). Co-Authored-By: Claude Opus 4.6 --- protocols/context.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/protocols/context.md b/protocols/context.md index 24d24a1..d6c2fac 100644 --- a/protocols/context.md +++ b/protocols/context.md @@ -14,6 +14,11 @@ Load when needed for alignment/verification: ### State - `.specwright/state/workflow.json` — Current progress, gate results, lock status +### Reference Documents +Load on demand when codebase structure knowledge is needed: + +- `.specwright/LANDSCAPE.md` — Codebase architecture and module knowledge (optional) + ## Initialization Checks **Before any operation:** From e08f9bd17884dc25cb69206e6507e71b6b482a98 Mon Sep 17 00:00:00 2001 From: MacAttak Date: Sun, 15 Feb 2026 17:59:00 +1100 Subject: [PATCH 3/8] feat(skills): add survey phase to sw-init for LANDSCAPE.md generation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds optional codebase survey after detection. Tightened Detection, Git workflow, and Gate configuration constraints (732 → 654 words). Co-Authored-By: Claude Opus 4.6 --- skills/sw-init/SKILL.md | 34 ++++++++++++---------------------- 1 file changed, 12 insertions(+), 22 deletions(-) diff --git a/skills/sw-init/SKILL.md b/skills/sw-init/SKILL.md index 899b894..d2b14a2 100644 --- a/skills/sw-init/SKILL.md +++ b/skills/sw-init/SKILL.md @@ -40,10 +40,12 @@ When complete, ALL of the following exist: ## Constraints **Detection (MEDIUM freedom):** -- Scan the codebase to detect: language(s), framework(s), package manager, - test runner, existing linting/formatting, git workflow, CI/CD presence. -- Read dependency manifests (package.json, go.mod, requirements.txt, Cargo.toml, etc.). -- Don't guess what you can detect. Don't ask what you can infer. +- Scan codebase: language(s), framework(s), package manager, test runner, linting/formatting, git workflow, CI/CD. Read dependency manifests. Don't guess what you can detect. + +**Survey (MEDIUM freedom):** +- After detection, survey the codebase using Glob/Grep/Read: directory structure, entry points, module dependencies, conventions, integration points, gotchas. +- Produce `.specwright/LANDSCAPE.md` per `protocols/landscape.md` format. User approves before saving. +- Optional — if user declines, skip. LANDSCAPE.md is never required. **User conversation (HIGH freedom):** - Ask the user about things you CANNOT detect from the codebase: @@ -71,19 +73,10 @@ When complete, ALL of the following exist: - The user must approve the charter before it's saved. **Git workflow configuration (MEDIUM freedom):** -- Detect git workflow by scanning: - - Branch names (`git branch -a`): look for `develop`, `release/*`, `hotfix/*` (→ gitflow), feature branches (→ github-flow/trunk-based) - - Remote configuration (`git remote -v`) - - CI files referencing branch names (`.github/workflows/*.yml`, `.gitlab-ci.yml`, `Jenkinsfile`) -- Present detected workflow with confidence level to the user. -- Use AskUserQuestion to confirm or override: - - Strategy: trunk-based, github-flow, gitflow, custom - - Branch prefix (default: `feat/` or detected) - - Merge strategy: squash, rebase, merge - - PR required: yes/no - - Commit format: conventional, freeform, custom -- Store results in `config.json` `git` section. See `protocols/git.md` for field reference. -- If existing `config.json` has old git schema (missing new fields like `mergeStrategy`, `prRequired`, `branchPerWorkUnit`): offer to migrate by adding new fields with sensible defaults. +- Detect workflow by scanning branch names, remotes, CI files. Present detected strategy with confidence. +- Confirm via AskUserQuestion: strategy (trunk-based/github-flow/gitflow/custom), branch prefix, merge strategy, PR required, commit format. +- Store in `config.json` `git` section per `protocols/git.md`. +- If old git schema detected: offer migration with sensible defaults. **Configuration (LOW freedom):** - Write `.specwright/config.json` with detected and configured values. @@ -92,11 +85,8 @@ When complete, ALL of the following exist: - Follow `protocols/state.md` for state file format. **Gate configuration (MEDIUM freedom):** -- Ask the user which quality checks matter to them. -- Default gates: build, security, spec-compliance. Others based on what's available. -- If the project has a test runner: enable test quality gate. -- If the project has a linter: enable lint gate. -- Configure thresholds based on user's stated expectations. +- Ask user which quality checks matter. Defaults: build, security, spec-compliance. +- Enable test/lint gates if detected. Configure thresholds per user expectations. ## Protocol References From cc63ea340f68e228768e78c6e0363019ee17d928 Mon Sep 17 00:00:00 2001 From: MacAttak Date: Sun, 15 Feb 2026 17:59:36 +1100 Subject: [PATCH 4/8] feat(skills): add landscape-aware research to sw-design MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Research phase loads LANDSCAPE.md first if available, refreshes inline when stale. Tightened Change requests constraint (607 → 610 words). Co-Authored-By: Claude Opus 4.6 --- skills/sw-design/SKILL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/sw-design/SKILL.md b/skills/sw-design/SKILL.md index 9908eb0..fcd0086 100644 --- a/skills/sw-design/SKILL.md +++ b/skills/sw-design/SKILL.md @@ -56,8 +56,8 @@ When warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strate - Default to Full when uncertain. **Research (HIGH freedom):** -- Understand the codebase BEFORE designing. Scan code, dependencies, APIs, existing patterns. -- Check `.specwright/patterns.md` and `.specwright/learnings/INDEX.md` if they exist. Reference relevant patterns in design.md. +- If `.specwright/LANDSCAPE.md` exists, load it first. If stale per `protocols/landscape.md`, refresh inline. Use as baseline for research. +- Scan code, dependencies, APIs, existing patterns. Check `.specwright/patterns.md` and `.specwright/learnings/INDEX.md` if they exist. - Delegate to `specwright-researcher` (external docs) and `specwright-architect` (deep analysis) as needed. - Produce `context.md` summarizing findings for downstream agents. @@ -70,7 +70,7 @@ When warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strate - Skip for straightforward requests. **Change requests (MEDIUM freedom):** -- If `design.md` exists with argument: treat as change request, re-run critic. Without argument: ask — redesign, continue, or describe changes. +- `design.md` exists + argument: change request, re-run critic. No argument: ask — redesign, continue, or changes. **User checkpoints:** - Ask for hard constraints before research (record in design.md). Share findings after research, alternatives after design, resolutions after critic. From 867b7e5ef220bb83ee37a2f79b73c90f08ea6e09 Mon Sep 17 00:00:00 2001 From: MacAttak Date: Sun, 15 Feb 2026 18:00:24 +1100 Subject: [PATCH 5/8] feat(skills): add landscape update phase to sw-learn MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit After capturing learnings, incrementally updates LANDSCAPE.md for modules changed in the work unit. Tightened Persistence, Enrichment, and Compaction constraints (623 → 589 words). Co-Authored-By: Claude Opus 4.6 --- skills/sw-learn/SKILL.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/skills/sw-learn/SKILL.md b/skills/sw-learn/SKILL.md index 19a28db..9631ff0 100644 --- a/skills/sw-learn/SKILL.md +++ b/skills/sw-learn/SKILL.md @@ -70,19 +70,18 @@ work benefits. - If directory empty, missing, or <2 files: silently skip. **Persistence (LOW freedom):** -- Write `.specwright/learnings/{work-id}.json` only when at least one finding is promoted. No file on all-dismissed. -- Schema: `{ workId, timestamp (ISO 8601), findings: [{ category, source, description, proposedRule, disposition }] }` -- Categories: `build | security | testing | architecture | friction`. Sources: `gate-evidence | git-log | plan | insights`. Dispositions: `promoted-constitution | promoted-patterns | dismissed`. +- Write `.specwright/learnings/{work-id}.json` only when at least one finding is promoted. +- Schema: `{ workId, timestamp, findings: [{ category, source, description, proposedRule, disposition }] }` + +**Landscape update (MEDIUM freedom):** +- After persistence, if `.specwright/LANDSCAPE.md` exists: identify modules affected by this work unit (git diff), re-scan affected modules, merge updates. Show diff, user approves. Update `Snapshot:` timestamp. +- If LANDSCAPE.md doesn't exist: silently skip. **Enrichment (MEDIUM freedom):** -- Optional phase governed by `protocols/insights.md` for session pattern enrichment. -- Reference the protocol for facets, privacy, staleness, and fallback behavior. -- Silently skip if insights unavailable or stale per protocol rules. +- Optional per `protocols/insights.md`. Silently skip if unavailable or stale. **Compaction (MEDIUM freedom):** -- Runs after persistence when triggers met, governed by `protocols/learning-lifecycle.md`. -- Groups raw learnings into themed summaries with INDEX.md. Reference protocol for thresholds and formats. -- Silently skip if threshold not met per protocol rules. +- Per `protocols/learning-lifecycle.md`. Silently skip if threshold not met. ## Protocol References @@ -91,6 +90,7 @@ work benefits. - `protocols/state.md` -- workflow state reading - `protocols/insights.md` -- session pattern enrichment - `protocols/learning-lifecycle.md` -- compaction triggers and lifecycle +- `protocols/landscape.md` -- codebase reference document format ## Failure Modes From 1e34ccba7629e5eb7374b52f3773c4123c1ff112 Mon Sep 17 00:00:00 2001 From: MacAttak Date: Sun, 15 Feb 2026 18:01:06 +1100 Subject: [PATCH 6/8] docs(design): document LANDSCAPE.md as reference document Adds Reference Documents section, LANDSCAPE.md to directory tree, and landscape protocol to protocols table. Anchor document language unchanged. Co-Authored-By: Claude Opus 4.6 --- DESIGN.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/DESIGN.md b/DESIGN.md index c8a16d4..43eb6d4 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -34,6 +34,11 @@ How the user wants code written. Testing standards, coding conventions, security **CHARTER.md** -- Technology Vision What is this repo? What are we building? Who are the consumers? Architectural invariants. The things that don't change. Referenced by plan to ensure alignment, validated by verify. +## Reference Documents + +**LANDSCAPE.md** -- Codebase Knowledge (optional) +Persistent cache of codebase structure: architecture, modules, conventions, integration points, gotchas. Not an anchor document — it accelerates design research but never blocks workflow. Created by sw-init (survey phase), read by sw-design (with inline refresh when stale), incrementally updated by sw-learn after shipping. Format and freshness rules in `protocols/landscape.md`. + ## Skills (14) ### User-Facing (9) @@ -105,8 +110,9 @@ Extracted once in `protocols/`, referenced by skills. Loaded on demand. | `context.md` | Config/state/anchor doc loading | ~100 | | `insights.md` | External CC insights data access | ~150 | | `learning-lifecycle.md` | Compaction triggers, tier structure, theme format | ~150 | +| `landscape.md` | Codebase reference doc format, freshness, updates | ~180 | -Total: ~1850 tokens (loaded on demand, not all at once). +Total: ~2030 tokens (loaded on demand, not all at once). ## Skill Anatomy @@ -180,6 +186,7 @@ Runtime state (created by init): ├── config.json # Project configuration ├── CONSTITUTION.md # Development practices ├── CHARTER.md # Technology vision +├── LANDSCAPE.md # Codebase knowledge (optional) ├── state/ │ └── workflow.json # Current state └── work/ # Work unit artifacts (specs, evidence, plans) From d321b66c211e0f8c27204f78aefdccb3d0a514f0 Mon Sep 17 00:00:00 2001 From: MacAttak Date: Sun, 15 Feb 2026 18:21:41 +1100 Subject: [PATCH 7/8] fix(verify): resolve wiring and spec compliance findings - Add LANDSCAPE.md to sw-init Configuration constraint (AC-3.4) - Add explicit timestamp update and missing-case to sw-design refresh (AC-4.2, W5) - Add protocols/landscape.md to sw-init and sw-design Protocol References (W1, W2) - Add landscape.md to CLAUDE.md protocols list (W3) - Update README.md protocol count to 11 (W4) - Reword sw-learn landscape update to use available tools (W6) Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 1 + README.md | 2 +- skills/sw-design/SKILL.md | 3 ++- skills/sw-init/SKILL.md | 3 ++- skills/sw-learn/SKILL.md | 2 +- 5 files changed, 7 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 83fc003..8d149af 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -51,6 +51,7 @@ Skills reference shared protocols in `protocols/` for fragile operations: - `context.md` -- Anchor doc and config loading - `insights.md` -- External Claude Code insights data access - `learning-lifecycle.md` -- Compaction triggers and tiered memory +- `landscape.md` -- Codebase reference document format and freshness rules ## Key Rules diff --git a/README.md b/README.md index 1a380e1..f7c43d5 100644 --- a/README.md +++ b/README.md @@ -196,7 +196,7 @@ See `DESIGN.md` for the complete architecture document. ``` specwright/ ├── skills/ # 14 SKILL.md files (9 user + 5 gates) -├── protocols/ # 10 shared protocols (loaded on demand) +├── protocols/ # 11 shared protocols (loaded on demand) ├── agents/ # 6 custom subagent definitions ├── hooks/ # Session lifecycle hooks ├── DESIGN.md # Full architecture diff --git a/skills/sw-design/SKILL.md b/skills/sw-design/SKILL.md index fcd0086..b552b41 100644 --- a/skills/sw-design/SKILL.md +++ b/skills/sw-design/SKILL.md @@ -56,7 +56,7 @@ When warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strate - Default to Full when uncertain. **Research (HIGH freedom):** -- If `.specwright/LANDSCAPE.md` exists, load it first. If stale per `protocols/landscape.md`, refresh inline. Use as baseline for research. +- If `.specwright/LANDSCAPE.md` exists, load it first. If stale per `protocols/landscape.md`, refresh inline and update `Snapshot:` timestamp. If missing, proceed without. Use as baseline for research. - Scan code, dependencies, APIs, existing patterns. Check `.specwright/patterns.md` and `.specwright/learnings/INDEX.md` if they exist. - Delegate to `specwright-researcher` (external docs) and `specwright-architect` (deep analysis) as needed. - Produce `context.md` summarizing findings for downstream agents. @@ -88,6 +88,7 @@ When warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strate - `protocols/context.md` -- anchor doc and config loading - `protocols/delegation.md` -- agent delegation for research and critic - `protocols/recovery.md` -- compaction recovery +- `protocols/landscape.md` -- codebase reference document format ## Failure Modes diff --git a/skills/sw-init/SKILL.md b/skills/sw-init/SKILL.md index d2b14a2..386ccf4 100644 --- a/skills/sw-init/SKILL.md +++ b/skills/sw-init/SKILL.md @@ -81,7 +81,7 @@ When complete, ALL of the following exist: **Configuration (LOW freedom):** - Write `.specwright/config.json` with detected and configured values. - Create `.specwright/state/workflow.json` with empty initial state. -- Create directory structure: `.specwright/state/`, `.specwright/work/`, `.specwright/baselines/`, `.specwright/learnings/`. +- Create directory structure: `.specwright/state/`, `.specwright/work/`, `.specwright/baselines/`, `.specwright/learnings/`. If survey produced LANDSCAPE.md, include it (optional). - Follow `protocols/state.md` for state file format. **Gate configuration (MEDIUM freedom):** @@ -93,6 +93,7 @@ When complete, ALL of the following exist: - `protocols/state.md` -- workflow.json initialization - `protocols/context.md` -- config.json format - `protocols/git.md` -- git config field reference and strategy definitions +- `protocols/landscape.md` -- codebase reference document format ## Failure Modes diff --git a/skills/sw-learn/SKILL.md b/skills/sw-learn/SKILL.md index 9631ff0..9e752f4 100644 --- a/skills/sw-learn/SKILL.md +++ b/skills/sw-learn/SKILL.md @@ -74,7 +74,7 @@ work benefits. - Schema: `{ workId, timestamp, findings: [{ category, source, description, proposedRule, disposition }] }` **Landscape update (MEDIUM freedom):** -- After persistence, if `.specwright/LANDSCAPE.md` exists: identify modules affected by this work unit (git diff), re-scan affected modules, merge updates. Show diff, user approves. Update `Snapshot:` timestamp. +- After persistence, if `.specwright/LANDSCAPE.md` exists: identify affected modules from evidence and plan artifacts, re-scan those modules, merge updates. Show diff, user approves. Update `Snapshot:` timestamp. - If LANDSCAPE.md doesn't exist: silently skip. **Enrichment (MEDIUM freedom):** From 5e8ea5187f691ecc87b70cdcdabe74a3a5162498 Mon Sep 17 00:00:00 2001 From: MacAttak Date: Sun, 15 Feb 2026 18:24:13 +1100 Subject: [PATCH 8/8] fix(skills): add Bash to sw-learn allowed-tools for git log access Pre-existing gap surfaced by verify (P11): sw-learn references git log in Inputs and Discovery but lacked Bash in allowed-tools. Co-Authored-By: Claude Opus 4.6 --- skills/sw-learn/SKILL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/skills/sw-learn/SKILL.md b/skills/sw-learn/SKILL.md index 9e752f4..6a19a2d 100644 --- a/skills/sw-learn/SKILL.md +++ b/skills/sw-learn/SKILL.md @@ -9,6 +9,7 @@ allowed-tools: - Read - Write - Edit + - Bash - Glob - Grep - AskUserQuestion