diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 073b23a..48d0e40 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -67,7 +67,7 @@ jobs: - name: Update README.md run: | - sed -i "s/^\*\*Version\*\*: .*/**Version**: ${{ steps.next.outputs.version }}/" README.md + sed -i "s/MIT License · v[0-9]*\.[0-9]*\.[0-9]*/MIT License · v${{ steps.next.outputs.version }}/" README.md - name: Update banner version run: | @@ -79,20 +79,26 @@ jobs: NEW_VERSION="${{ steps.next.outputs.version }}" BODY=$(cat /tmp/changelog_body.md) - # Create new section - { - # Copy header (lines before first ## [) - sed -n '1,/^## \[/{ /^## \[/!p }' CHANGELOG.md - echo "" - echo "## [${NEW_VERSION}] - ${DATE}" - echo "" - echo "### Changed" - echo "" - echo "$BODY" - echo "" - # Copy rest of file starting from first ## [ - sed -n '/^## \[/,$p' CHANGELOG.md - } > CHANGELOG.tmp && mv CHANGELOG.tmp CHANGELOG.md + # Skip if a hand-written entry already exists for this version + if grep -q "^## \[${NEW_VERSION}\]" CHANGELOG.md; then + echo "CHANGELOG already contains entry for ${NEW_VERSION}, updating date only" + sed -i "s/^## \[${NEW_VERSION}\].*/## [${NEW_VERSION}] - ${DATE}/" CHANGELOG.md + else + # Create new section + { + # Copy header (lines before first ## [) + sed -n '1,/^## \[/{ /^## \[/!p }' CHANGELOG.md + echo "" + echo "## [${NEW_VERSION}] - ${DATE}" + echo "" + echo "### Changed" + echo "" + echo "$BODY" + echo "" + # Copy rest of file starting from first ## [ + sed -n '/^## \[/,$p' CHANGELOG.md + } > CHANGELOG.tmp && mv CHANGELOG.tmp CHANGELOG.md + fi - name: Create release branch and PR env: diff --git a/CHANGELOG.md b/CHANGELOG.md index e3c4fae..ced1d68 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,14 +8,31 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.7.0] - 2026-02-16 +### Added + +- **Codebase Landscape** (`LANDSCAPE.md`) — Persistent codebase knowledge document covering architecture, modules, conventions, and gotchas. Created during `/sw-init` (optional survey phase), loaded by `/sw-design` with automatic staleness refresh, incrementally updated by `/sw-learn` after shipping. New `protocols/landscape.md` defines format, size targets (500-3000 words), and freshness rules (7-day default, configurable). (#26) +- **Codebase Audit** (`/sw-audit`) — Periodic health check skill that finds systemic issues per-change gates miss. Four dimensions: architecture, complexity, consistency, debt. Delegates to architect and reviewer agents, synthesizes findings into persistent `AUDIT.md` with stable finding IDs across re-runs. Adaptive intensity: focused (path), standard (small projects), full (large projects, parallel agents). New `protocols/audit.md` defines finding format, ID matching, lifecycle, and freshness. (#27) +- **Audit integration with design** — `/sw-design` now loads `AUDIT.md` during research and surfaces relevant findings for the area being designed +- **Audit integration with learn** — `/sw-learn` checks if shipped work addresses open audit findings and marks them resolved +### Changed + +- `protocols/context.md` — Reference Documents section now includes both `LANDSCAPE.md` and `AUDIT.md` (optional, load on demand) +- Skill count: 14 → 15 (10 user-facing + 5 gates) +- Protocol count: 11 → 12 +- README updated with Codebase Knowledge and Health section, version footer corrected +- DESIGN.md Reference Documents section documents both LANDSCAPE.md and AUDIT.md lifecycles ## [0.6.0] - 2026-02-15 -### Changed +### Added -- feat(skills): adaptive intensity, session hooks, stop guard, compaction recovery (#23) +- **Adaptive intensity** — `/sw-design` triages requests as Full, Lite, or Quick based on complexity. Lite skips design.md, Quick skips straight to build +- **Session hooks** — `hooks/session-start.md` loads recovery protocol on compaction detection +- **Stop guard** — `/sw-guard` can now configure stop-on-error hooks for CI/CD layers +- **Compaction recovery** — All stateful skills check for compaction and resume from last completed step ## [0.5.2] - 2026-02-13 @@ -35,25 +52,6 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [0.5.0] - 2026-02-12 -### Changed - -- fix(docs): address stale wording from wiring gate findings -- docs: update README and CHANGELOG for design/plan split -- docs: update DESIGN.md and CLAUDE.md for design/plan split -- feat(skills): update sw-verify and sw-status for design/plan split -- feat(skills): add design.md to sw-build inputs and context envelope -- feat(skills): rewrite sw-plan for decomposition and specs only -- fix(protocols): add null-to-designing transition in state table -- feat(skills): create sw-design skill for interactive solution architecture -- feat(protocols): add designing status and sw-design handoff -- fix(agents): correct executor description, add tester negative constraints -- docs(design): add behavioral discipline as principle #7 -- feat(sw-build): scope REFACTOR step and add behavioral envelope -- feat(sw-plan): add simplicity bias to Design phase -- feat(agents): add Karpathy-aligned behavioral discipline sections - -## [0.5.0] - 2026-02-13 - ### Added - **sw-design skill** — Interactive solution architecture with research, adversarial critic, and user approval. Produces `design.md`, `context.md`, and conditional artifacts (`decisions.md`, `data-model.md`, `contracts.md`, `testing-strategy.md`, `infra.md`, `migrations.md`) diff --git a/README.md b/README.md index 25befba..d2effb2 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,8 @@ Specwright closes the **entire loop** — design, plan, build, verify, ship, lea - Evidence-based PRs with gate proof for every acceptance criterion - Compaction recovery reloads full context automatically - Learning system captures failures and promotes patterns across sessions +- Codebase knowledge persists across sessions — no re-discovering the same architecture +- Periodic health checks find systemic debt that per-change gates miss - One install, configure once, works with any language or framework ## What Makes This Different @@ -48,6 +50,10 @@ Specwright focuses on the **verification and evidence** side — the part where **Learning System** — Failures are captured, patterns are promoted, and learnings compact into tiered memory (index, themes, raw data). The system gets smarter with every session. Knowledge survives context windows. +**Codebase Knowledge** — During init, Specwright surveys your codebase and builds a persistent knowledge document (`LANDSCAPE.md`) covering architecture, modules, conventions, and gotchas. Design phases load this instantly instead of re-scanning. It stays current — refreshed when stale, incrementally updated after every shipped work unit. + +**Codebase Health Checks** — Run `/sw-audit` periodically to find systemic issues that per-change gates miss: architecture debt, complexity growth, convention drift, accumulated workarounds. Findings persist in `AUDIT.md` with stable IDs across re-runs. Design phases surface relevant findings. The learn phase resolves them when addressed. + **Compaction Recovery** — All stateful skills support resume-from-crash. When Claude's context window compacts, Specwright reloads full state from disk. The only plugin in this space that handles context loss gracefully. ## How It Works @@ -62,6 +68,7 @@ graph LR F -.->|next work unit| D F --> G["/sw-learn"] G -.->|patterns feed back| B + H["/sw-audit"] -.->|findings feed into| B style A fill:#1e293b,stroke:#f59e0b,color:#f8fafc style B fill:#1e293b,stroke:#f59e0b,color:#f8fafc @@ -70,6 +77,7 @@ graph LR style E fill:#1e293b,stroke:#f59e0b,color:#f8fafc style F fill:#1e293b,stroke:#f59e0b,color:#f8fafc style G fill:#1e293b,stroke:#f59e0b,color:#f8fafc + style H fill:#1e293b,stroke:#f59e0b,color:#f8fafc ``` | Phase | What Happens | Key Innovation | @@ -81,6 +89,7 @@ graph LR | **Verify** | 5 quality gates with evidence capture | Findings shown inline, not just pass/fail badges | | **Ship** | PR with acceptance criteria mapped to evidence | Every requirement traceable to code + test | | **Learn** | Capture patterns, promote to constitution | Knowledge compounds across sessions | +| **Audit** | Periodic health check — architecture, complexity, consistency, debt | Finds systemic issues gates miss. Run anytime. | ## Quick Start @@ -111,6 +120,30 @@ Then design, plan, and iterate per work unit: /sw-ship ``` +## Codebase Knowledge and Health + +Two optional features keep Specwright informed about your codebase across sessions: + +**Landscape** (`LANDSCAPE.md`) — A persistent map of your codebase's architecture, modules, conventions, and integration points. Created automatically during `/sw-init` if you opt in. The design phase loads it for instant context instead of re-scanning every time. Updated incrementally after each shipped work unit. + +- Created by: `/sw-init` (survey phase, optional) +- Consumed by: `/sw-design` (auto-refreshed when stale) +- Updated by: `/sw-learn` (after shipping) + +**Audit** (`AUDIT.md`) — A persistent record of systemic codebase health issues. Run `/sw-audit` when you want a health check — it's not part of the regular workflow, so use it whenever it makes sense: before starting a large feature, after a refactoring sprint, or on a regular cadence. + +``` +/sw-audit # auto-triage: standard or full based on codebase size +/sw-audit src/api/ # focused: analyze only the specified path +/sw-audit --full # full: parallel analysis across all dimensions +``` + +Findings persist across runs with stable IDs. When you design new work, relevant findings are surfaced automatically. When you ship work that addresses a finding, the learn phase marks it resolved. + +- Created by: `/sw-audit` (run anytime) +- Consumed by: `/sw-design` (surfaces relevant findings during research) +- Resolved by: `/sw-learn` (marks addressed findings as resolved) + ## Six Specialized Agents Specwright delegates to purpose-built agents — each with a distinct role, model, and adversarial stance: @@ -136,14 +169,20 @@ Every work unit passes through configurable gates before shipping. **Default sta | **Wiring** | Orphaned files, unused exports, layer violations, circular deps | WARN | | **Spec** | Every acceptance criterion mapped to code + test evidence | BLOCK | -## Anchor Documents +## Persistent Documents -Two persistent documents drive all decisions and survive context compaction: +Two **anchor documents** drive all decisions and survive context compaction: **`CONSTITUTION.md`** — Development practices the AI must follow. Testing standards, coding conventions, security requirements. Not suggestions — rules. **`CHARTER.md`** — Technology vision and architectural invariants. What this project is, who consumes it, what doesn't change. +Two optional **reference documents** accelerate research and track health: + +**`LANDSCAPE.md`** — Codebase knowledge: architecture, modules, conventions, gotchas. Loaded on demand, never blocks workflow. + +**`AUDIT.md`** — Codebase health findings: systemic debt, complexity growth, convention drift. Loaded on demand, findings have stable IDs. + ## Skills @@ -218,5 +257,5 @@ Specwright is open source under the MIT license. ---

- Built by ObsidianOwl · MIT License · v0.5.0 + Built by ObsidianOwl · MIT License · v0.6.0