Skip to content

Commit 252cc13

Browse files
tbitcsoz-agent
tbitcs
and
oz-agent
committed
feat: uppercase governance filenames + community templates (#42)
- All scaffolded governance/doc files now use uppercase stems (RULES.md, WORKFLOW.md, ROLES.md, CONTEXT-BUDGET.md, VERIFICATION.md, DRIFT-METRICS.md, ARCHITECTURE.md, WORKFLOW.md) - Upgrader migrates legacy lowercase files to uppercase on upgrade (handles case-insensitive FS via two-step rename) - New community templates: CONTRIBUTING.md, LICENSE (MIT/Apache-2.0), SECURITY.md, CODE_OF_CONDUCT.md, PR template, issue templates - Config: added license field (default MIT) and community_files list - Auditor now recommends CONTRIBUTING.md and LICENSE - Updated all integrations, templates, tests, and docs Closes #42 Co-Authored-By: Oz <oz-agent@warp.dev>
1 parent eb22145 commit 252cc13

34 files changed

Lines changed: 623 additions & 161 deletions

‎.warp/rules/kr260-board-identity.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# KR260 Board Identity — COM Port Safety Rule
2+
3+
## Rule
4+
5+
**NEVER assume which COM port corresponds to kria-a or kria-b based on port number or
6+
position alone.** COM port assignments can change across reboots, USB hub resets, cable
7+
swaps, or OS re-enumeration events.
8+
9+
## Required Practice
10+
11+
Before issuing any board-specific command, configuration, or measurement over a serial
12+
console (COM port), **always verify the hostname first**:
13+
14+
```
15+
login: atomicrail
16+
password: ...
17+
atomicrail@kria-a:~$ ← confirm this matches your intent
18+
```
19+
20+
Or, if already logged in:
21+
22+
```bash
23+
hostname
24+
```
25+
26+
## Background
27+
28+
On 2026-04-02, after flashing and rebooting both KR260 boards, the COM port assignments
29+
were found to be **swapped relative to the previous session**. What was kria-a's port
30+
is now kria-b's port and vice versa. This was only caught because the board banner and
31+
hostname were checked in the boot log.
32+
33+
## Scope
34+
35+
Applies to all dual-board KR260 (kria-a / kria-b) lab work in the AtomicRail / cpsc-engine-rtl
36+
project whenever serial consoles, minicom/PuTTY/Warp sessions, or any tool that references
37+
a COM port by name or number is used.
38+
39+
## Consequence of Violation
40+
41+
Running a benchmark, flashing a bitstream, or modifying network configuration on the wrong
42+
board produces invalid results and may require board recovery.

‎README.md‎

Lines changed: 28 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -36,14 +36,36 @@ pip install specsmith
3636
## Quick Start
3737

3838
```bash
39-
specsmith init # New project (interactive)
40-
specsmith init --config scaffold.yml # New project (from config)
41-
specsmith import --project-dir ./my-project # Adopt existing project
42-
specsmith audit --project-dir ./my-project # Health check
43-
specsmith export --project-dir ./my-project # Compliance report
44-
specsmith doctor --project-dir ./my-project # Tool check
39+
# Install
40+
pip install specsmith
41+
42+
# New project (interactive)
43+
specsmith init
44+
45+
# Adopt an existing project
46+
specsmith import --project-dir ./my-project
47+
48+
# Check governance health
49+
specsmith audit --project-dir ./my-project
50+
51+
# Generate architecture docs interactively
52+
specsmith architect --project-dir ./my-project
53+
54+
# Start an AI agent session (universal pattern)
55+
# From any governed repo root:
56+
/agent AGENTS.md
4557
```
4658

59+
### Starting an AI Agent Session
60+
61+
The universal pattern for any specsmith-governed project:
62+
63+
```
64+
/agent AGENTS.md
65+
```
66+
67+
This works in Warp, Claude Code, Cursor, and any agent that reads markdown context files. The agent loads AGENTS.md (the governance hub), reads LEDGER.md for session state, and picks up from the last recorded action.
68+
4769
## 30 Project Types
4870

4971
**Software:** Python, Rust, Go, C/C++, .NET, JS/TS, mobile, monorepo, microservices, DevOps/IaC, data/ML, browser extensions.

‎docs/AGENT-WORKFLOW-SPEC.md‎

Lines changed: 25 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -53,12 +53,12 @@ Detailed governance rules are split into focused, referenceable documents under
5353

5454
| File | Content | Load timing |
5555
| ---- | ------- | ----------- |
56-
| `docs/governance/rules.md` | Hard rules, stop conditions | Every session start |
57-
| `docs/governance/workflow.md` | Session lifecycle, proposal format, ledger format | Every session start |
58-
| `docs/governance/roles.md` | Agent role definition, behavioral rules | Every session start |
59-
| `docs/governance/context-budget.md` | Context window management, credit optimization | Every session start |
60-
| `docs/governance/verification.md` | Verification standards, acceptance criteria | When performing verification |
61-
| `docs/governance/drift-metrics.md` | Drift detection, feedback loops, health signals | On `audit` command or session start |
56+
| `docs/governance/RULES.md` | Hard rules, stop conditions | Every session start |
57+
| `docs/governance/WORKFLOW.md` | Session lifecycle, proposal format, ledger format | Every session start |
58+
| `docs/governance/ROLES.md` | Agent role definition, behavioral rules | Every session start |
59+
| `docs/governance/CONTEXT-BUDGET.md` | Context window management, credit optimization | Every session start |
60+
| `docs/governance/VERIFICATION.md` | Verification standards, acceptance criteria | When performing verification |
61+
| `docs/governance/DRIFT-METRICS.md` | Drift detection, feedback loops, health signals | On `audit` command or session start |
6262

6363
Agents read AGENTS.md in full on every session. The governance docs listed with "Every session start" timing are read immediately after. Other governance docs are loaded on demand when the task requires them. This lazy-loading approach minimizes credit consumption (see Section 25).
6464

@@ -80,11 +80,11 @@ Rules:
8080

8181
Project overview, architecture summary, component descriptions, repository structure, near-term goals, and current status. Must be kept in sync with architectural reality.
8282

83-
### 2.4 docs/architecture.md
83+
### 2.4 docs/ARCHITECTURE.md
8484

8585
System architecture: components, boundaries, interfaces, runtime modes, platform expectations, constraints, and design principles.
8686

87-
### 2.5 docs/workflow.md
87+
### 2.5 docs/WORKFLOW.md
8888

8989
Development workflow: the work loop, proposal rules, PR expectations, cross-platform rules, documentation rules, verification rules, and milestones.
9090

@@ -109,10 +109,10 @@ When documents conflict, precedence is resolved top-down:
109109
1. **AGENTS.md + docs/governance/*** — behavioral rules, hard constraints, stop conditions (highest). Governance docs inherit AGENTS.md's authority because AGENTS.md explicitly delegates to them.
110110
2. **README.md** — project intent and scope
111111
3. **docs/REQUIREMENTS.md** — what the system must do
112-
4. **docs/architecture.md** — how the system is structured
112+
4. **docs/ARCHITECTURE.md** — how the system is structured
113113
5. **docs/TEST_SPEC.md** — how the system is verified
114114
6. **LEDGER.md** — what has been done and what remains (sole authority for session state)
115-
7. **docs/workflow.md** — how work proceeds
115+
7. **docs/WORKFLOW.md** — how work proceeds
116116
8. **docs/services.md** — platform-specific startup/service behavior
117117

118118
If a requirement contradicts the architecture, the requirement wins. If AGENTS.md contradicts a requirement, AGENTS.md wins.
@@ -130,7 +130,7 @@ Agents MUST follow structured session flows. Five session types are defined.
130130
Trigger: fresh conversation targeting the repository.
131131

132132
```
133-
Load AGENTS.md, README.md, docs/architecture.md, docs/workflow.md,
133+
Load AGENTS.md, README.md, docs/ARCHITECTURE.md, docs/WORKFLOW.md,
134134
docs/services.md (if it exists), docs/REQUIREMENTS.md, docs/TEST_SPEC.md, and LEDGER.md.
135135
136136
Output:
@@ -899,16 +899,16 @@ When an agent is asked to scaffold a new project using this workflow:
899899

900900
### Step 3: Create governance files
901901
- **AGENTS.md** — focused hub (~100–150 lines): project identity, platform, tech stack, file registry pointing to `docs/governance/*`, quick command reference, and project-type-specific rules from the relevant Section 17 subsection.
902-
- **docs/governance/rules.md** — hard rules (H1–H9) and stop conditions, adapted from Sections 8–9
903-
- **docs/governance/workflow.md** — session lifecycle, proposal format, ledger format, adapted from Sections 4–6
904-
- **docs/governance/roles.md** — agent role definition and behavioral rules, adapted from Section 7
905-
- **docs/governance/context-budget.md** — context window management and credit optimization, adapted from Sections 10 and 25
906-
- **docs/governance/verification.md** — verification and acceptance standards, adapted from Sections 11–12
907-
- **docs/governance/drift-metrics.md** — drift detection and feedback loop protocol, adapted from Section 26
902+
- **docs/governance/RULES.md** — hard rules (H1–H9) and stop conditions, adapted from Sections 8–9
903+
- **docs/governance/WORKFLOW.md** — session lifecycle, proposal format, ledger format, adapted from Sections 4–6
904+
- **docs/governance/ROLES.md** — agent role definition and behavioral rules, adapted from Section 7
905+
- **docs/governance/CONTEXT-BUDGET.md** — context window management and credit optimization, adapted from Sections 10 and 25
906+
- **docs/governance/VERIFICATION.md** — verification and acceptance standards, adapted from Sections 11–12
907+
- **docs/governance/DRIFT-METRICS.md** — drift detection and feedback loop protocol, adapted from Section 26
908908
- **README.md** — project overview, architecture summary, component descriptions, structure, goals, status
909909
- **LEDGER.md** — bootstrap entry recording the scaffold creation
910-
- **docs/architecture.md** — component model, boundaries, interfaces, platform expectations, runtime modes
911-
- **docs/workflow.md** — work loop, proposal rules, milestones, cross-platform rules, verification rules
910+
- **docs/ARCHITECTURE.md** — component model, boundaries, interfaces, platform expectations, runtime modes
911+
- **docs/WORKFLOW.md** — work loop, proposal rules, milestones, cross-platform rules, verification rules
912912
- **docs/services.md** — (if applicable) platform service/startup expectations
913913
- **docs/REQUIREMENTS.md** — initial requirements derived from architecture (may be sparse)
914914
- **docs/TEST_SPEC.md** — initial test specifications linked to requirements (may be sparse)
@@ -1165,15 +1165,15 @@ This is an estimate of actual session cost, useful for identifying wasteful task
11651165

11661166
On session start, agents SHOULD load only:
11671167
- `AGENTS.md`
1168-
- `docs/governance/rules.md`
1169-
- `docs/governance/context-budget.md`
1168+
- `docs/governance/RULES.md`
1169+
- `docs/governance/CONTEXT-BUDGET.md`
11701170
- recent `LEDGER.md`
11711171

11721172
Load these on demand:
1173-
- `docs/governance/workflow.md` when preparing proposals or ledger entries
1174-
- `docs/governance/roles.md` when role boundaries are relevant
1175-
- `docs/governance/verification.md` when testing, auditing, or accepting work
1176-
- `docs/governance/drift-metrics.md` when running `audit` or diagnosing process health
1173+
- `docs/governance/WORKFLOW.md` when preparing proposals or ledger entries
1174+
- `docs/governance/ROLES.md` when role boundaries are relevant
1175+
- `docs/governance/VERIFICATION.md` when testing, auditing, or accepting work
1176+
- `docs/governance/DRIFT-METRICS.md` when running `audit` or diagnosing process health
11771177

11781178
### 25.5 Response economy rules
11791179

‎docs/site/commands.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,7 @@ specsmith architect --project-dir ./my-project
166166
specsmith architect --project-dir ./my-project --non-interactive
167167
```
168168

169-
**What it does:** Scans for modules, languages, dependencies, git history, and existing architecture docs. In interactive mode, prompts for component names, purposes, interfaces, data flow, and deployment notes. Generates a rich `docs/architecture.md`.
169+
**What it does:** Scans for modules, languages, dependencies, git history, and existing architecture docs. In interactive mode, prompts for component names, purposes, interfaces, data flow, and deployment notes. Generates a rich `docs/ARCHITECTURE.md`.
170170

171171
**Options:**
172172

‎docs/site/getting-started.md‎

Lines changed: 24 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -57,19 +57,23 @@ my-tool/
5757
├── AGENTS.md # Governance hub
5858
├── LEDGER.md # Change ledger
5959
├── README.md # Project readme
60+
├── CONTRIBUTING.md # Contribution guide
61+
├── SECURITY.md # Vulnerability reporting
62+
├── CODE_OF_CONDUCT.md # Contributor Covenant
63+
├── LICENSE # MIT (configurable)
6064
├── pyproject.toml # Python project config
6165
├── scaffold.yml # specsmith config (saved)
6266
├── .gitignore / .gitattributes
6367
├── docs/
6468
│ ├── governance/
65-
│ │ ├── rules.md # Hard rules H1-H9
66-
│ │ ├── workflow.md # Session lifecycle
67-
│ │ ├── roles.md # Agent boundaries
68-
│ │ ├── context-budget.md # Token optimization
69-
│ │ ├── verification.md # Tools: ruff, mypy, pytest
70-
│ │ └── drift-metrics.md # Health signals
71-
│ ├── architecture.md
72-
│ ├── workflow.md
69+
│ │ ├── RULES.md # Hard rules H1-H9
70+
│ │ ├── WORKFLOW.md # Session lifecycle
71+
│ │ ├── ROLES.md # Agent boundaries
72+
│ │ ├── CONTEXT-BUDGET.md # Token optimization
73+
│ │ ├── VERIFICATION.md # Tools: ruff, mypy, pytest
74+
│ │ └── DRIFT-METRICS.md # Health signals
75+
│ ├── ARCHITECTURE.md
76+
│ ├── WORKFLOW.md
7377
│ ├── REQUIREMENTS.md
7478
│ └── TEST_SPEC.md
7579
├── src/my_tool/
@@ -82,7 +86,9 @@ my-tool/
8286
│ └── exec.cmd / exec.sh
8387
├── .github/
8488
│ ├── workflows/ci.yml # ruff + mypy + pytest + pip-audit
85-
│ └── dependabot.yml # pip + github-actions
89+
│ ├── dependabot.yml # pip + github-actions
90+
│ ├── PULL_REQUEST_TEMPLATE.md # Governance-aware PR template
91+
│ └── ISSUE_TEMPLATE/ # Bug report + feature request
8692
├── .warp/skills/SKILL.md # Warp/Oz governance skill
8793
└── CLAUDE.md # Claude Code governance
8894
```
@@ -106,7 +112,15 @@ specsmith doctor --project-dir my-tool
106112

107113
### Step 5: Open in Your AI Agent
108114

109-
Open the project in Warp, Claude Code, Cursor, or your preferred agent. The agent reads `AGENTS.md` and knows the governance rules. Type `start` to begin a governed session.
115+
From the project root, use the universal session start command:
116+
117+
```
118+
/agent AGENTS.md
119+
```
120+
121+
This works in Warp/Oz, Claude Code, Cursor, and any agent that reads context files. The agent reads `AGENTS.md` (the governance hub), loads `LEDGER.md` for session state, and follows the closed-loop workflow.
122+
123+
After the agent is loaded, you can use the quick command `start` to trigger the full session start protocol (sync, update check, branch check).
110124

111125
## Tutorial: Import an Existing Project
112126

‎docs/site/governance.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,10 @@ Every specsmith-governed project has this authority hierarchy — higher files o
2323
1. **AGENTS.md + docs/governance/*** — Highest. Governance rules are law.
2424
2. **README.md** — Project intent and scope.
2525
3. **docs/REQUIREMENTS.md** — What the system must do.
26-
4. **docs/architecture.md** — How the system is structured.
26+
4. **docs/ARCHITECTURE.md** — How the system is structured.
2727
5. **docs/TEST_SPEC.md** — How the system is verified.
2828
6. **LEDGER.md** — Sole authority for session state (what's been done, what's next).
29-
7. **docs/workflow.md** — How work proceeds (milestones, PR expectations).
29+
7. **docs/WORKFLOW.md** — How work proceeds (milestones, PR expectations).
3030

3131
## AGENTS.md — The Governance Hub
3232

@@ -46,14 +46,14 @@ When AGENTS.md is kept small (~100-150 lines), governance details are delegated
4646

4747
| File | Content | When Loaded |
4848
|------|---------|-------------|
49-
| `rules.md` | Hard rules H1-H9, stop conditions | Every session start |
50-
| `workflow.md` | Session lifecycle, proposal format, ledger format | Every session start |
51-
| `roles.md` | Agent role boundaries, behavioral rules | Every session start |
52-
| `context-budget.md` | Context management, credit optimization | Every session start |
53-
| `verification.md` | Verification standards, tools listing, acceptance criteria | When performing verification |
54-
| `drift-metrics.md` | Drift detection, feedback loops, health signals | On audit or session start |
55-
56-
This lazy-loading approach minimizes token consumption — agents only load verification.md when they're actually running tests, not at every session start.
49+
| `RULES.md` | Hard rules H1-H9, stop conditions | Every session start |
50+
|| `WORKFLOW.md` | Session lifecycle, proposal format, ledger format | Every session start |
51+
|| `ROLES.md` | Agent role boundaries, behavioral rules | Every session start |
52+
|| `CONTEXT-BUDGET.md` | Context management, credit optimization | Every session start |
53+
|| `VERIFICATION.md` | Verification standards, tools listing, acceptance criteria | When performing verification |
54+
|| `DRIFT-METRICS.md` | Drift detection, feedback loops, health signals | On audit or session start |
55+
56+
This lazy-loading approach minimizes token consumption — agents only load VERIFICATION.md when they're actually running tests, not at every session start.
5757

5858
## LEDGER.md — The Session Memory
5959

‎docs/site/index.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,13 +43,29 @@ specsmith init
4343
# Adopt an existing project
4444
specsmith import --project-dir ./my-project
4545

46+
# Generate architecture docs
47+
specsmith architect --project-dir ./my-project
48+
4649
# Check governance health
4750
specsmith audit --project-dir ./my-project
4851

52+
# Track AI credit spend
53+
specsmith credits summary --project-dir ./my-project
54+
4955
# Generate compliance report
5056
specsmith export --project-dir ./my-project
5157
```
5258

59+
### Starting an AI Agent Session
60+
61+
From any specsmith-governed project root, the universal command to begin a session:
62+
63+
```
64+
/agent AGENTS.md
65+
```
66+
67+
This loads the governance hub, session state from LEDGER.md, and project rules. Works in Warp/Oz, Claude Code, Cursor, Copilot, and any agent that reads markdown context.
68+
5369
## Documentation Guide
5470

5571
| Section | What You'll Learn |

‎src/specsmith/architect.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ def generate_architecture(
148148
doc += "\n"
149149

150150
# Write
151-
arch_path = root / "docs" / "architecture.md"
151+
arch_path = root / "docs" / "ARCHITECTURE.md"
152152
arch_path.parent.mkdir(parents=True, exist_ok=True)
153153
arch_path.write_text(doc, encoding="utf-8")
154154
return arch_path

0 commit comments

Comments
 (0)