diff --git a/CLAUDE.md b/CLAUDE.md index 8d149af..e46d782 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,6 +19,7 @@ Spec-driven app development with quality gates. Ensures the user gets what they | `sw-guard` | Detect stack and interactively configure guardrails (hooks, CI, settings). | | `sw-status` | Current state and progress. | | `sw-learn` | Post-ship capture of patterns and learnings. | +| `sw-audit` | Periodic codebase health check. Finds systemic tech debt. | ## Anchor Documents @@ -52,6 +53,7 @@ Skills reference shared protocols in `protocols/` for fragile operations: - `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 +- `audit.md` -- Codebase health findings format, IDs, and lifecycle ## Key Rules diff --git a/DESIGN.md b/DESIGN.md index 43eb6d4..d9178e0 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -39,9 +39,12 @@ What is this repo? What are we building? Who are the consumers? Architectural in **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) +**AUDIT.md** -- Codebase Health Findings (optional) +Persistent record of systemic issues that per-change gates miss: architecture debt, complexity growth, convention drift, accumulated workarounds. Created by sw-audit, surfaced by sw-design during research, resolved by sw-learn after shipping. Findings have stable IDs across re-runs. Resolved findings purge after 90 days. Format, matching, and freshness rules in `protocols/audit.md`. -### User-Facing (9) +## Skills (15) + +### User-Facing (10) | Skill | Purpose | Key Innovation | |-------|---------|----------------| @@ -54,6 +57,7 @@ Persistent cache of codebase structure: architecture, modules, conventions, inte | `sw-status` | Where am I, what's done, what's next | Supports --reset to abandon work | | `sw-guard` | Detect stack, configure guardrails interactively | Layer-by-layer approval (session, commit, push, CI/CD) | | `sw-learn` | Post-ship capture. What worked, what to remember | Promotes patterns to constitution | +| `sw-audit` | Periodic codebase health check | Finds systemic debt gates miss. Feeds findings into design + learn | ### Internal Gate Skills (5) @@ -111,8 +115,9 @@ Extracted once in `protocols/`, referenced by skills. Loaded on demand. | `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 | +| `audit.md` | Codebase health findings format, IDs, matching, lifecycle | ~180 | -Total: ~2030 tokens (loaded on demand, not all at once). +Total: ~2210 tokens (loaded on demand, not all at once). ## Skill Anatomy @@ -156,7 +161,7 @@ Target: 600 tokens per SKILL.md (40% of the 1,500 token ceiling). ``` specwright/ -├── skills/ # SKILL.md files (14 skills) +├── skills/ # SKILL.md files (15 skills) │ ├── sw-init/ # User-facing │ ├── sw-design/ │ ├── sw-plan/ @@ -166,6 +171,7 @@ specwright/ │ ├── sw-guard/ │ ├── sw-status/ │ ├── sw-learn/ +│ ├── sw-audit/ │ ├── gate-build/ # Internal (invoked by verify) │ ├── gate-tests/ │ ├── gate-security/ @@ -187,6 +193,7 @@ Runtime state (created by init): ├── CONSTITUTION.md # Development practices ├── CHARTER.md # Technology vision ├── LANDSCAPE.md # Codebase knowledge (optional) +├── AUDIT.md # Codebase health findings (optional) ├── state/ │ └── workflow.json # Current state └── work/ # Work unit artifacts (specs, evidence, plans) diff --git a/README.md b/README.md index f7c43d5..25befba 100644 --- a/README.md +++ b/README.md @@ -167,6 +167,7 @@ Two persistent documents drive all decisions and survive context compaction: | `/sw-guard` | Configure guardrails (hooks, CI) | | `/sw-status` | Progress and state | | `/sw-learn` | Pattern capture | +| `/sw-audit` | Codebase health check | @@ -195,8 +196,8 @@ See `DESIGN.md` for the complete architecture document. ``` specwright/ -├── skills/ # 14 SKILL.md files (9 user + 5 gates) -├── protocols/ # 11 shared protocols (loaded on demand) +├── skills/ # 15 SKILL.md files (10 user + 5 gates) +├── protocols/ # 12 shared protocols (loaded on demand) ├── agents/ # 6 custom subagent definitions ├── hooks/ # Session lifecycle hooks ├── DESIGN.md # Full architecture diff --git a/protocols/audit.md b/protocols/audit.md new file mode 100644 index 0000000..99e08b3 --- /dev/null +++ b/protocols/audit.md @@ -0,0 +1,25 @@ +# Audit Protocol + +## Format + +`.specwright/AUDIT.md` — optional reference document. Never blocks workflow. + +Header: `Snapshot:` (ISO 8601), `Scope:` (full | focused: {path}), `Dimensions:` (list), `Findings:` (count, B/W/I). + +Sections: Summary, Findings (`[SEVERITY] F{n}: {title}` — Dimension, Location, Description, Impact, Recommendation, Status), Resolved (resolver ID + date). + +## Finding IDs + +Format: `F{n}`, never reused. On re-run: match by dimension + location. Matched → reuse ID. Unmatched new → next ID. Unmatched existing → `stale`. + +## Lifecycle + +Open → Stale (unmatched on re-run) → Resolved (`## Resolved`, with work unit ID + date) → Purged (resolved >90 days, removed on re-run). + +## Size + +Target 1000-2000 words, cap 3000. Overflow: keep highest-severity, truncate INFO. + +## Freshness + +`Snapshot:` timestamp. Stale after 30 days (configurable: `config.audit.stalenessThresholdDays`). Missing: proceed without. diff --git a/protocols/context.md b/protocols/context.md index d6c2fac..62a3048 100644 --- a/protocols/context.md +++ b/protocols/context.md @@ -18,6 +18,7 @@ Load when needed for alignment/verification: Load on demand when codebase structure knowledge is needed: - `.specwright/LANDSCAPE.md` — Codebase architecture and module knowledge (optional) +- `.specwright/AUDIT.md` — Codebase health findings and tech debt tracking (optional) ## Initialization Checks diff --git a/skills/sw-audit/SKILL.md b/skills/sw-audit/SKILL.md new file mode 100644 index 0000000..6cd4fb6 --- /dev/null +++ b/skills/sw-audit/SKILL.md @@ -0,0 +1,86 @@ +--- +name: sw-audit +description: >- + Periodic codebase health check. Analyzes architecture, complexity, + consistency, and debt across the full codebase. Produces persistent + findings in AUDIT.md. +argument-hint: "[path | --full]" +allowed-tools: + - Read + - Write + - Glob + - Grep + - Task + - AskUserQuestion +--- + +# Specwright Audit + +## Goal + +Find systemic codebase issues that per-change quality gates miss. +Architecture debt, complexity growth, convention drift, and accumulated +workarounds compound silently. Surface them, let the user prioritize, +and persist findings for future design cycles. + +## Inputs + +- The codebase itself +- `.specwright/CONSTITUTION.md` -- practices to check against +- `.specwright/AUDIT.md` -- prior findings (if exists, for ID matching) +- `.specwright/LANDSCAPE.md` -- module structure (if exists, for triage) +- `.specwright/config.json` -- audit config (optional `audit` section) + +## Outputs + +- `.specwright/AUDIT.md` -- findings per `protocols/audit.md` format +- Findings presented to user grouped by dimension before saving + +## Constraints + +**Scope (LOW freedom):** +- This skill reads and analyzes. It NEVER modifies source code, creates branches, runs builds, or starts work units. +- Does NOT create `currentWork` in workflow.json. Does NOT require a lock. Can run while a work unit is in progress. +- On compaction: re-run from scratch (no state to recover). + +**Triage (MEDIUM freedom):** +- Determine intensity from argument and codebase size: + - Path argument → **Focused**: analyze specified directory/module only + - `--full` argument → **Full**: parallel agents, all dimensions + - No argument → auto-triage: Standard (<50 files) or Full (50+ files) +- If LANDSCAPE.md exists, use module count to inform triage. + +**Analysis (HIGH freedom):** +- Four dimensions: architecture, complexity, consistency, debt. +- Delegate per `protocols/delegation.md`: + - `specwright-architect`: architecture + complexity (structural analysis) + - `specwright-reviewer`: consistency + debt (convention and quality analysis) +- Standard intensity: 2 agent calls (sequential or parallel). +- Full intensity: up to 4 parallel calls (one per dimension). +- Include constitution practices as the baseline for consistency checks. + +**Synthesis (LOW freedom):** +- Agents return raw findings. The skill itself aggregates results. +- If prior AUDIT.md exists: match findings per `protocols/audit.md` (dimension + location). Reuse matched IDs, assign new IDs for unmatched. Mark unmatched prior findings as stale. +- Purge resolved findings older than 90 days. +- Enforce size cap per protocol. Write AUDIT.md. + +**Presentation (MEDIUM freedom):** +- Show findings grouped by dimension. For each: severity, location, description, impact, recommendation. +- Use AskUserQuestion to let user adjust severity or dismiss findings before saving. +- Maximum 20 findings per run. If more, keep highest-severity. + +## Protocol References + +- `protocols/audit.md` -- finding format, IDs, matching, lifecycle +- `protocols/delegation.md` -- agent delegation +- `protocols/context.md` -- config and anchor doc loading + +## Failure Modes + +| Condition | Action | +|-----------|--------| +| No codebase files found | STOP: "No source files to audit." | +| Agents unavailable | Fall back to inline analysis (less thorough) | +| Prior AUDIT.md parse error | WARN, start fresh (no ID continuity) | +| Compaction during audit | Re-run from scratch | diff --git a/skills/sw-design/SKILL.md b/skills/sw-design/SKILL.md index b552b41..6270c4b 100644 --- a/skills/sw-design/SKILL.md +++ b/skills/sw-design/SKILL.md @@ -57,8 +57,9 @@ When warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strate **Research (HIGH freedom):** - 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. +- If `.specwright/AUDIT.md` exists and fresh per `protocols/audit.md`, surface relevant findings for the area being designed. - 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. +- Delegate to `specwright-researcher` and `specwright-architect` as needed. - Produce `context.md` summarizing findings for downstream agents. **Design (HIGH freedom):** @@ -73,8 +74,7 @@ When warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strate - `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. -- The user must approve the design before it is saved. +- Ask for hard constraints before research. Share findings after research, alternatives after design, resolutions after critic. User approves design before saving. **State mutations (LOW freedom):** - Follow `protocols/state.md` for all workflow.json updates. @@ -89,6 +89,7 @@ When warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strate - `protocols/delegation.md` -- agent delegation for research and critic - `protocols/recovery.md` -- compaction recovery - `protocols/landscape.md` -- codebase reference document format +- `protocols/audit.md` -- codebase health findings format ## Failure Modes diff --git a/skills/sw-learn/SKILL.md b/skills/sw-learn/SKILL.md index 6a19a2d..58b8b8a 100644 --- a/skills/sw-learn/SKILL.md +++ b/skills/sw-learn/SKILL.md @@ -54,30 +54,31 @@ work benefits. **Discovery (HIGH freedom):** - Scan evidence files, git log, and plan.md for patterns worth remembering. -- Look for: things that broke, things surprisingly hard, things that worked well. +- Look for: what broke, what was hard, what worked well. **Presentation (MEDIUM freedom):** - Group by category (build, security, testing, architecture). Show: what happened, why it matters, proposed rule. -- Use AskUserQuestion for curation: promote to constitution, promote to patterns, or dismiss. -- Maximum 5-7 learnings per session. +- Use AskUserQuestion for curation: promote to constitution, patterns, or dismiss. Maximum 5-7 learnings. **Promotion (LOW freedom):** -- If promoting to constitution: add a new practice with ID (e.g., S6, Q5) and clear wording. -- If promoting to patterns: append to `.specwright/patterns.md` (create if doesn't exist). -- User must approve exact wording before saving. +- Constitution: add practice with ID (e.g., S6, Q5). Patterns: append to `.specwright/patterns.md` (create if missing). +- User approves exact wording before saving. **Retrospective (MEDIUM freedom):** -- When `.specwright/learnings/` has 2+ prior files, surface recurring patterns across units citing work IDs. -- If directory empty, missing, or <2 files: silently skip. +- When 2+ prior learning files exist, surface recurring patterns across units. **Persistence (LOW freedom):** -- Write `.specwright/learnings/{work-id}.json` only when at least one finding is promoted. +- Write `.specwright/learnings/{work-id}.json` when any finding is promoted. - Schema: `{ workId, timestamp, findings: [{ category, source, description, proposedRule, disposition }] }` **Landscape update (MEDIUM freedom):** - 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. +**Audit resolution (MEDIUM freedom):** +- After landscape update, if `.specwright/AUDIT.md` exists: check if work unit's changed files overlap with open finding locations. If finding is addressed, move to `## Resolved` with work unit ID. User approves. +- If AUDIT.md doesn't exist: silently skip. + **Enrichment (MEDIUM freedom):** - Optional per `protocols/insights.md`. Silently skip if unavailable or stale. @@ -92,6 +93,7 @@ work benefits. - `protocols/insights.md` -- session pattern enrichment - `protocols/learning-lifecycle.md` -- compaction triggers and lifecycle - `protocols/landscape.md` -- codebase reference document format +- `protocols/audit.md` -- codebase health findings format ## Failure Modes