Skip to content

Commit cfbce1b

Browse files
tbitcsoz-agent
tbitcs
and
oz-agent
committed
merge: sync main skills commits into develop
Co-Authored-By: Oz <oz-agent@warp.dev>
2 parents 8273dd4 + 67e0d92 commit cfbce1b

5 files changed

Lines changed: 455 additions & 10 deletions

File tree

‎.agents/skills/specsmith-audit/SKILL.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
name: specsmith-audit
3+
description: Run specsmith audit to check for governance drift between requirements, tests, and architecture. Required before advancing an AEE phase.
4+
---
5+
6+
# Specsmith Audit
7+
8+
Checks the project for drift between requirements (ARCHITECTURE.md), test cases,
9+
and the codebase. Must pass before advancing an AEE phase.
10+
11+
## How to run
12+
13+
```bash
14+
specsmith audit
15+
```
16+
17+
## Interpreting results
18+
19+
```
20+
29 PASS ← all requirements have matching tests and implementation
21+
2 WARN ← drift detected — investigate these
22+
0 FAIL
23+
```
24+
25+
**All items must be PASS or suppressed before `specsmith phase advance`.**
26+
27+
## When a WARN appears
28+
29+
1. Read the warning — it references a requirement ID (e.g. `R20`) and describes what's missing
30+
2. Fix it: add the missing test, update ARCHITECTURE.md, or implement the requirement
31+
3. Re-run `specsmith audit` to confirm it passes
32+
4. If it's a confirmed false positive: `specsmith audit --suppress <CODE>`
33+
34+
## Suppressing a false positive
35+
36+
Only suppress if you've verified the requirement IS met but the audit can't detect it:
37+
38+
```bash
39+
specsmith audit --suppress SEAL-XXXX-001
40+
```
41+
42+
Suppressions are permanent — use sparingly.
43+
44+
## Common causes of WARN
45+
46+
- Requirement in ARCHITECTURE.md has no corresponding test case
47+
- Test exists but requirement ID reference is missing from the test
48+
- Implementation exists but the architecture doc wasn't updated to match
49+
50+
## After fixing all warnings
51+
52+
```bash
53+
specsmith audit # confirm all pass
54+
specsmith phase advance # advance the phase
55+
specsmith save # commit the phase bump
56+
```
57+
58+
## Quick audit before a session
59+
60+
Run `specsmith audit` at the start of a session to catch drift from the previous
61+
session before making new changes.

‎.agents/skills/specsmith-save/SKILL.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
name: specsmith-save
3+
description: Run specsmith save to commit and push all current changes with governance state backup. Use at the end of any work session or after completing a feature/fix.
4+
---
5+
6+
# Specsmith Save
7+
8+
Saves governance state: backs up the ESDB, commits any staged/unstaged changes,
9+
and pushes to the remote.
10+
11+
## When to use
12+
13+
- At the end of any work session
14+
- After implementing a feature, fix, or refactor
15+
- After advancing a phase
16+
- Whenever the user says "save", "commit and push", or "specsmith save"
17+
18+
## How to run
19+
20+
```bash
21+
specsmith save
22+
```
23+
24+
## What it does (in order)
25+
26+
1. **ESDB backup** — snapshots the epistemic state database
27+
2. **Commit** — stages all changes and commits with a governance-aware message (or reports "Nothing to commit")
28+
3. **Push** — pushes the branch to origin (or reports "Everything up-to-date")
29+
30+
## Expected successful output
31+
32+
```
33+
✓ esdb_backup: JSON fallback (no WAL to backup)
34+
✓ commit: Nothing to commit ← or a commit hash
35+
✓ push: Everything up-to-date ← or "pushed to origin/branch"
36+
```
37+
38+
## If there are changes to commit
39+
40+
Specsmith auto-stages and commits. You can also pre-stage manually:
41+
42+
```bash
43+
git add -A
44+
git commit -m "feat: description
45+
46+
Co-Authored-By: Oz <oz-agent@warp.dev>"
47+
specsmith save # will see nothing to commit, just pushes
48+
```
49+
50+
## Do NOT use `git push` directly
51+
52+
Always use `specsmith save` — it ensures the ESDB backup runs before the push,
53+
keeping governance state consistent with the remote.

‎.agents/skills/specsmith/SKILL.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
name: specsmith
3+
description: Master reference for the specsmith AEE governance tool — key concepts, common commands, session workflow, phase advancement, and audit codes. Use whenever working in a specsmith-governed project.
4+
---
5+
6+
# Specsmith — Project Governance Tool
7+
8+
Specsmith is the AEE (Agile Epistemic Engineering) governance CLI. It manages
9+
requirements, phases, audit trails, and session state. It wraps git with
10+
governance-aware commits and backs up the epistemic state DB (ESDB).
11+
12+
## Key concepts
13+
14+
- **ESDB** — Epistemic State Database. Tracks certainty, audit state, session memory. Backed up on `specsmith save`.
15+
- **Phases** — AEE lifecycle: Inception → Elaboration → Construction → Transition → Validation → Hardening → Release.
16+
- **Ledger** — Running log of changes in `LEDGER.md`. Auto-updated by commits.
17+
- **Audit** — Checks requirements vs tests vs architecture for drift. Required before phase advance.
18+
- **Save** — ESDB backup + governance-aware git commit + push.
19+
20+
## Session workflow
21+
22+
```
23+
1. specsmith audit # check for drift before working
24+
2. <make code changes>
25+
3. specsmith save # commit + push + ESDB backup
26+
```
27+
28+
## Common commands
29+
30+
| Command | What it does |
31+
|---------|-------------|
32+
| `specsmith save` | ESDB backup → commit (if needed) → push |
33+
| `specsmith audit` | Drift/health check — requirements vs tests vs arch |
34+
| `specsmith audit --suppress <CODE>` | Accept a known false positive |
35+
| `specsmith phase` | Show current AEE phase |
36+
| `specsmith phase advance` | Advance to next phase (requires clean audit) |
37+
| `specsmith commit` | Governance-aware commit (wraps git commit) |
38+
| `specsmith ledger` | Show/manage the change ledger |
39+
| `specsmith compress` | Compress old ledger entries |
40+
| `specsmith req` | Manage requirements |
41+
| `specsmith test` | Manage test cases |
42+
| `specsmith status` | VCS/CI/PR status |
43+
| `specsmith skill list` | List built-in installable skills |
44+
| `specsmith skill install <slug>` | Install a skill into `.agents/skills/` |
45+
46+
## Commit conventions
47+
48+
Specsmith commits follow: `type: message` where type is one of:
49+
`feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`
50+
51+
Always append `Co-Authored-By: Oz <oz-agent@warp.dev>` when committing as an AI agent.
52+
53+
## Important rules
54+
55+
- **Never use `git commit` directly** — use `specsmith save` or `specsmith commit`.
56+
- **Run `specsmith audit` before advancing a phase** — a phase advance with drift will fail.
57+
- **Suppressed audit findings** are stored permanently; only suppress genuine false positives.
58+
- After `specsmith save` outputs `✓ push: Everything up-to-date`, the repo is fully clean.
59+
60+
## Audit result codes
61+
62+
- `PASS` — requirement/test/arch is consistent
63+
- `WARN` — drift detected, investigate
64+
- `SKIP` / suppressed — accepted false positive
65+
- IDs like `R20`, `R21` — requirement IDs in ARCHITECTURE.md
66+
67+
## Phase advancement
68+
69+
```bash
70+
specsmith audit # must be all-pass (or suppressed)
71+
specsmith phase advance # bumps phase, writes ledger entry
72+
specsmith save # commit the phase bump
73+
```
74+
75+
## Installing skills in any project
76+
77+
```bash
78+
specsmith skill install specsmith # this reference card
79+
specsmith skill install specsmith-save # save workflow
80+
specsmith skill install specsmith-audit # audit workflow
81+
```

‎src/specsmith/skills/__init__.py‎

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -11,16 +11,17 @@
1111
1212
Domain modules
1313
~~~~~~~~~~~~~~
14-
governance — project governance, verification, review, release workflows
15-
embedded — RTOS/BSP: Zephyr, Yocto, FreeRTOS, NuttX, Buildroot, Azure RTOS …
16-
hardware — EDA: KiCad, Altium, Vivado, Quartus, GTKWave, OpenOCD, JTAG
17-
mobile — iOS (Xcode/Swift/TestFlight), Android (Gradle/ADB), Flutter, RN
18-
cloud — AWS CLI, Azure CLI, GCP, GitHub CLI (gh)
19-
devops — Docker, Kubernetes, Terraform, CI/CD pipelines
20-
ssh — SSH key management, remote-dev, WSL2
21-
cross_platform — CMake/vcpkg/conan, package managers, cross-OS CI
22-
productivity — Email, presentations, Gamma.ai, MS Office, LibreOffice
23-
corporate — Budgets, project mgmt, HR, fundraising, marketing, sales, legal
14+
governance — project governance, verification, review, release workflows
15+
specsmith_skills — specsmith self-referential skills (save, audit, reference)
16+
embedded — RTOS/BSP: Zephyr, Yocto, FreeRTOS, NuttX, Buildroot, Azure RTOS …
17+
hardware — EDA: KiCad, Altium, Vivado, Quartus, GTKWave, OpenOCD, JTAG
18+
mobile — iOS (Xcode/Swift/TestFlight), Android (Gradle/ADB), Flutter, RN
19+
cloud — AWS CLI, Azure CLI, GCP, GitHub CLI (gh)
20+
devops — Docker, Kubernetes, Terraform, CI/CD pipelines
21+
ssh — SSH key management, remote-dev, WSL2
22+
cross_platform — CMake/vcpkg/conan, package managers, cross-OS CI
23+
productivity — Email, presentations, Gamma.ai, MS Office, LibreOffice
24+
corporate — Budgets, project mgmt, HR, fundraising, marketing, sales, legal
2425
2526
Usage
2627
~~~~~
@@ -121,6 +122,7 @@ def _build_catalog() -> list[SkillEntry]:
121122
hardware,
122123
mobile,
123124
productivity,
125+
specsmith_skills,
124126
ssh,
125127
)
126128

@@ -136,6 +138,7 @@ def _build_catalog() -> list[SkillEntry]:
136138
+ productivity.SKILLS
137139
+ corporate.SKILLS
138140
+ docs.SKILLS
141+
+ specsmith_skills.SKILLS
139142
)
140143

141144

0 commit comments

Comments
 (0)