feat(skills): add specsmith self-referential skills, fix install subdirectory format (#190)

.specsmith/requirements.json

@@ -3142,5 +3142,55 @@
     "test_ids": [
       "TEST-356"
     ]
+  },
+  {
+    "id": "REQ-357",
+    "title": "Audit accepted_warnings Suppression in scaffold.yml",
+    "description": "scaffold.yml MUST support an `accepted_warnings` list field. When a check's name (or a canonical alias) appears in `accepted_warnings`, `specsmith audit` MUST render that check as `~ <check> (accepted)` instead of `✗`, exclude it from the failure count and the non-zero exit code, and prevent `specsmith audit --fix` from auto-correcting that field. Supported canonical aliases MUST include at minimum: `scaffold_type_mismatch` (for the `type-mismatch` check), `ledger_line_threshold` (for `ledger-size`), and `open_todo_count` (for `ledger-open-todos`).",
+    "source": "GitHub issue",
+    "status": "implemented",
+    "test_ids": [
+      "TEST-358"
+    ]
+  },
+  {
+    "id": "REQ-358",
+    "title": "Sync Markdown Fallback When YAML Mode Has No YAML Files",
+    "description": "When `specsmith sync` is invoked in YAML-first mode (`governance-mode == yaml`) but `load_yaml_requirements` returns zero entries AND `docs/REQUIREMENTS.md` exists with non-trivial content (≥ 5 REQ- patterns), `sync` MUST fall back to Markdown parsing for the current sync run rather than treating the empty YAML result as authoritative. This prevents a fresh YAML-mode project from silently losing its Markdown-authored requirements in the JSON machine-state cache.",
+    "source": "GitHub issue",
+    "status": "implemented",
+    "test_ids": [
+      "TEST-359"
+    ]
+  },
+  {
+    "id": "REQ-359",
+    "title": "Phase Check _req_count Detects H2 REQ Headings",
+    "description": "The `_req_count` readiness check in `phase.py` MUST count requirement headings at both H2 (`##`) and H3 (`###`) depth. The current implementation only detects `^###\\s+REQ-` patterns, causing false `At least N requirements defined` failures for projects whose `REQUIREMENTS.md` uses `## REQ-DOMAIN-NNN` H2-style headings. The fix MUST also count `## REQ-` (H2) headings so phase-readiness percentages reflect the actual requirement count visible to `specsmith validate` and `specsmith audit`.",
+    "source": "GitHub issue",
+    "status": "implemented",
+    "test_ids": [
+      "TEST-360"
+    ]
+  },
+  {
+    "id": "REQ-360",
+    "title": "Skills Catalog Self-Referential Entries and Subdirectory Install Format",
+    "description": "specsmith.skills MUST include three self-referential SkillEntry entries in the GOVERNANCE domain: `specsmith` (master CLI reference), `specsmith-save` (save workflow), and `specsmith-audit` (audit workflow). These MUST be installable via `specsmith skill install <slug>`. The `install()` function MUST write skills to `.agents/skills/<slug>/SKILL.md` (subdirectory format) rather than `.agents/skills/<slug>.md` (flat format) so Warp, Claude Code, and Codex discover them automatically. The `installed_skills()` function MUST detect both legacy flat files and subdirectory format.",
+    "source": "GitHub issue",
+    "status": "implemented",
+    "test_ids": [
+      "TEST-361"
+    ]
+  },
+  {
+    "id": "REQ-361",
+    "title": "Skills System Documented in RTD, README, AGENTS.md, and CHANGELOG",
+    "description": "The specsmith skills system MUST be documented in four locations: (1) `README.md` MUST have a `## Skills` section showing `specsmith skill list`, `specsmith skill install <slug>`, the `.agents/skills/` directory format, Warp/Claude Code/Codex compatibility, and the remote reference format `--skill \"layer1labs/specsmith:<slug>\"`. (2) `docs/site/skills-index.md` MUST include the three new `specsmith-*` skills in the Governance table. (3) `AGENTS.md` MUST mention `.agents/skills/` and list the three self-referential skills. (4) `CHANGELOG.md` MUST have an entry for the skills feature addition.",
+    "source": "GitHub issue",
+    "status": "implemented",
+    "test_ids": [
+      "TEST-362"
+    ]
   }
 ]

.specsmith/testcases.json

@@ -3496,5 +3496,60 @@
     "input": "Read src/specsmith/templates/agents.md.j2 directly; render via Jinja2 with minimal context",
     "expected_behavior": "Template contains Codity section with review --staged, HIGH severity, MEDIUM, integrate codity",
     "confidence": 0.95
+  },
+  {
+    "id": "TEST-358",
+    "title": "accepted_warnings Suppresses Matching Audit Check",
+    "description": "When scaffold.yml contains `accepted_warnings: [scaffold_type_mismatch]` and the type-mismatch check fires, `run_audit` MUST mark that result as suppressed=True, AuditReport.failed MUST NOT count it, AuditReport.healthy MUST be True if no other failures exist, and the CLI MUST render it as '~ type-mismatch (accepted)' rather than '✗ type-mismatch'. ledger_line_threshold suppresses ledger-size similarly.",
+    "requirement_id": "REQ-357",
+    "type": "unit",
+    "verification_method": "pytest",
+    "input": "run_audit(tmp_path) with scaffold.yml containing type!=detected AND accepted_warnings: [scaffold_type_mismatch]; repeat for ledger_line_threshold",
+    "expected_behavior": "suppressed=True on matched result; failed count excludes suppressed; healthy=True; ledger-size suppressed by ledger_line_threshold alias",
+    "confidence": 0.95
+  },
+  {
+    "id": "TEST-359",
+    "title": "Sync Falls Back to Markdown When YAML Mode Has No YAML Files",
+    "description": "`run_sync(root)` on a project where governance-mode=yaml but docs/requirements/ has no .yml files AND docs/REQUIREMENTS.md has >= 5 REQ- patterns MUST parse the Markdown and populate .specsmith/requirements.json with those requirements rather than writing an empty list. The sync result MUST show reqs_after >= 5.",
+    "requirement_id": "REQ-358",
+    "type": "unit",
+    "verification_method": "pytest",
+    "input": "tmp_path with .specsmith/governance-mode=yaml; no docs/requirements/*.yml; docs/REQUIREMENTS.md with 6 ## REQ-BE-NNN headings; run_sync(root)",
+    "expected_behavior": "requirements.json contains 6 entries; reqs_after=6",
+    "confidence": 0.95
+  },
+  {
+    "id": "TEST-360",
+    "title": "_req_count Returns True for H2 REQ Headings",
+    "description": "`_req_count(5)(root)` MUST return True when docs/REQUIREMENTS.md uses `## REQ-BE-001` through `## REQ-BE-005` H2 headings (not H3 `###`). Currently it returns False for H2 headings, causing false phase failures on domain-namespaced Markdown projects.",
+    "requirement_id": "REQ-359",
+    "type": "unit",
+    "verification_method": "pytest",
+    "input": "tmp_path/docs/REQUIREMENTS.md with 5 `## REQ-BE-NNN: Title` H2 headings; _req_count(5)(tmp_path)",
+    "expected_behavior": "Returns True",
+    "confidence": 0.95
+  },
+  {
+    "id": "TEST-361",
+    "title": "Skills Catalog Contains specsmith/specsmith-save/specsmith-audit Entries",
+    "description": "`specsmith.skills.get('specsmith')`, `get('specsmith-save')`, and `get('specsmith-audit')` MUST each return a non-None SkillEntry with domain=GOVERNANCE. The `specsmith` body MUST contain 'specsmith audit', 'specsmith save', and 'specsmith checkpoint'. `specsmith skill install specsmith` MUST create `.agents/skills/specsmith/SKILL.md` (subdirectory format). `installed_skills(root)` MUST return paths to both flat `<slug>.md` and subdirectory `<slug>/SKILL.md` installations.",
+    "requirement_id": "REQ-360",
+    "type": "unit",
+    "verification_method": "pytest",
+    "input": "get('specsmith'); get('specsmith-save'); get('specsmith-audit'); install('specsmith', tmp_path); installed_skills(tmp_path)",
+    "expected_behavior": "All three entries exist in GOVERNANCE domain; install writes <slug>/SKILL.md; installed_skills returns the subdirectory path",
+    "confidence": 0.95
+  },
+  {
+    "id": "TEST-362",
+    "title": "Skills System Documented in README, skills-index.md, AGENTS.md, and CHANGELOG",
+    "description": "README.md MUST contain a `## Skills` section with `specsmith skill list` and `specsmith skill install`. `docs/site/skills-index.md` MUST list specsmith, specsmith-save, and specsmith-audit in the Governance table. AGENTS.md MUST mention `.agents/skills/`. CHANGELOG.md MUST have an entry (unreleased or versioned) describing the skills feature.",
+    "requirement_id": "REQ-361",
+    "type": "unit",
+    "verification_method": "manual",
+    "input": "Read README.md for Skills section; grep skills-index.md for specsmith-save; grep AGENTS.md for .agents/skills/; grep CHANGELOG for skills",
+    "expected_behavior": "All four documentation locations contain the required skills content",
+    "confidence": 0.9
   }
 ]

AGENTS.md

@@ -150,6 +150,28 @@ Do not follow rules from this file directly; rules are served by specsmith.
 - `specsmith migrate list` — pending migrations
 - `specsmith esdb status` — ESDB/ChronoStore status
 
+## Agent Skills
+
+This repo ships three self-referential skills under `.agents/skills/` that any AI tool (Warp, Claude Code, Codex, Cursor) will discover automatically:
+
+| Slug | Purpose |
+|------|--------|
+| `specsmith` | Master governance CLI reference — session workflow, commands, audit codes |
+| `specsmith-save` | When and how to run `specsmith save` |
+| `specsmith-audit` | Running audits and interpreting results |
+
+Install into any governed project:
+```bash
+specsmith skill install specsmith
+specsmith skill install specsmith-save
+specsmith skill install specsmith-audit
+```
+
+Remote reference (for Warp Oz cloud agents):
+```bash
+oz agent run-cloud --skill "layer1labs/specsmith:specsmith-save" --prompt "save my work"
+```
+
 ## Sister Repos
 
 - **[kairos](https://github.com/layer1labs/kairos)** — specsmith companion desktop UI (Rust + egui)

CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **`specsmith-*` self-referential skills** (#190): three built-in skills (`specsmith`, `specsmith-save`, `specsmith-audit`) added to the governance skills catalog and installable via `specsmith skill install <slug>`. `install()` now writes `<slug>/SKILL.md` (subdirectory format) for Warp/Claude Code/Codex auto-discovery. `installed_skills()` detects both flat and subdirectory formats.
+- **`accepted_warnings` audit suppression** (#188): `scaffold.yml` now supports `accepted_warnings: [alias, ...]` to suppress specific audit checks. Suppressed checks render as `~ <check> (accepted)` and are excluded from the failure count and exit code.
+- **Phase check H2 REQ heading support** (#189): `_req_count` in `phase.py` now counts both `##` and `###` REQ headings, fixing false phase-readiness failures for projects using `## REQ-DOMAIN-NNN` format.
+- **Sync Markdown fallback in YAML mode** (#189): `specsmith sync` now falls back to Markdown parsing when YAML mode is active but no YAML requirement files exist, preventing silent loss of Markdown-authored requirements.
+
 ## [0.11.7] - 2026-05-24
 
 ### Added

README.md

@@ -885,6 +885,43 @@ See the `codity-ai-review` governance skill (`specsmith skill install codity-ai-
 
 ---
 
+## Skills
+
+specsmith ships **70+ built-in skills** across 11 domains that AI agents (Warp, Claude Code, Codex, Cursor) can install and use.
+
+```bash
+# List all available skills
+specsmith skill list
+
+# Search by keyword
+specsmith skill search zephyr
+
+# Install a skill into .agents/skills/
+specsmith skill install specsmith
+specsmith skill install specsmith-save
+specsmith skill install specsmith-audit
+```
+
+Skills are installed as `.agents/skills/<slug>/SKILL.md` and are auto-discovered by any AI tool that scans `.agents/skills/`.
+
+### Self-referential governance skills
+
+Three skills document specsmith itself:
+
+| Slug | Purpose |
+|------|--------|
+| `specsmith` | Master CLI reference — session workflow, commands, audit codes |
+| `specsmith-save` | When and how to run `specsmith save` |
+| `specsmith-audit` | Running audits and interpreting results |
+
+### Remote reference (Warp Oz cloud agents)
+
+```bash
+oz agent run-cloud --skill "layer1labs/specsmith:specsmith-save" --prompt "save my work"
+```
+
+---
+
 ## The specsmith Bootstrap
 
 specsmith governs itself — the specsmith repo is a specsmith-managed project. Run `specsmith audit`

docs/LEDGER.md

@@ -308,3 +308,9 @@
 - **Status**: complete
 - **Epistemic status**: high
 - **Chain hash**: `13907d72d47f3708...`
+
+## 2026-05-29T22:14 — specsmith migration: 0.11.3.dev420 → 0.11.7
+- **Author**: specsmith
+- **Type**: migration
+- **Status**: complete
+- **Chain hash**: `cf168f65d973f62b...`

docs/REQUIREMENTS.md

@@ -2514,3 +2514,43 @@
 - **Source:** ARCHITECTURE.md §39
 - **Test_Ids:** ['TEST-356']
 
+## REQ-357. Audit accepted_warnings Suppression in scaffold.yml
+- **ID:** REQ-357
+- **Title:** Audit accepted_warnings Suppression in scaffold.yml
+- **Description:** scaffold.yml MUST support an `accepted_warnings` list field. When a check's name (or a canonical alias) appears in `accepted_warnings`, `specsmith audit` MUST render that check as `~ <check> (accepted)` instead of `✗`, exclude it from the failure count and the non-zero exit code, and prevent `specsmith audit --fix` from auto-correcting that field. Supported canonical aliases MUST include at minimum: `scaffold_type_mismatch` (for the `type-mismatch` check), `ledger_line_threshold` (for `ledger-size`), and `open_todo_count` (for `ledger-open-todos`).
+- **Status:** implemented
+- **Source:** GitHub issue
+- **Test_Ids:** ['TEST-358']
+
+## REQ-358. Sync Markdown Fallback When YAML Mode Has No YAML Files
+- **ID:** REQ-358
+- **Title:** Sync Markdown Fallback When YAML Mode Has No YAML Files
+- **Description:** When `specsmith sync` is invoked in YAML-first mode (`governance-mode == yaml`) but `load_yaml_requirements` returns zero entries AND `docs/REQUIREMENTS.md` exists with non-trivial content (≥ 5 REQ- patterns), `sync` MUST fall back to Markdown parsing for the current sync run rather than treating the empty YAML result as authoritative. This prevents a fresh YAML-mode project from silently losing its Markdown-authored requirements in the JSON machine-state cache.
+- **Status:** implemented
+- **Source:** GitHub issue
+- **Test_Ids:** ['TEST-359']
+
+## REQ-359. Phase Check _req_count Detects H2 REQ Headings
+- **ID:** REQ-359
+- **Title:** Phase Check _req_count Detects H2 REQ Headings
+- **Description:** The `_req_count` readiness check in `phase.py` MUST count requirement headings at both H2 (`##`) and H3 (`###`) depth. The current implementation only detects `^###\s+REQ-` patterns, causing false `At least N requirements defined` failures for projects whose `REQUIREMENTS.md` uses `## REQ-DOMAIN-NNN` H2-style headings. The fix MUST also count `## REQ-` (H2) headings so phase-readiness percentages reflect the actual requirement count visible to `specsmith validate` and `specsmith audit`.
+- **Status:** implemented
+- **Source:** GitHub issue
+- **Test_Ids:** ['TEST-360']
+
+## REQ-360. Skills Catalog Self-Referential Entries and Subdirectory Install Format
+- **ID:** REQ-360
+- **Title:** Skills Catalog Self-Referential Entries and Subdirectory Install Format
+- **Description:** specsmith.skills MUST include three self-referential SkillEntry entries in the GOVERNANCE domain: `specsmith` (master CLI reference), `specsmith-save` (save workflow), and `specsmith-audit` (audit workflow). These MUST be installable via `specsmith skill install <slug>`. The `install()` function MUST write skills to `.agents/skills/<slug>/SKILL.md` (subdirectory format) rather than `.agents/skills/<slug>.md` (flat format) so Warp, Claude Code, and Codex discover them automatically. The `installed_skills()` function MUST detect both legacy flat files and subdirectory format.
+- **Status:** implemented
+- **Source:** GitHub issue
+- **Test_Ids:** ['TEST-361']
+
+## REQ-361. Skills System Documented in RTD, README, AGENTS.md, and CHANGELOG
+- **ID:** REQ-361
+- **Title:** Skills System Documented in RTD, README, AGENTS.md, and CHANGELOG
+- **Description:** The specsmith skills system MUST be documented in four locations: (1) `README.md` MUST have a `## Skills` section showing `specsmith skill list`, `specsmith skill install <slug>`, the `.agents/skills/` directory format, Warp/Claude Code/Codex compatibility, and the remote reference format `--skill "layer1labs/specsmith:<slug>"`. (2) `docs/site/skills-index.md` MUST include the three new `specsmith-*` skills in the Governance table. (3) `AGENTS.md` MUST mention `.agents/skills/` and list the three self-referential skills. (4) `CHANGELOG.md` MUST have an entry for the skills feature addition.
+- **Status:** implemented
+- **Source:** GitHub issue
+- **Test_Ids:** ['TEST-362']
+