Skip to content

Commit 3a202af

Browse files
tbitcstbitcs
committed
chore: update project files
1 parent 0241617 commit 3a202af

4 files changed

Lines changed: 201 additions & 20 deletions

File tree

‎.specsmith/agent-tools.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"schema_version": 1,
3+
"primary_governance_command": "specsmith_run",
4+
"slash_prefix": "/specsmith",
5+
"verb_shortcuts": [
6+
"audit",
7+
"commit",
8+
"doctor",
9+
"load",
10+
"pull",
11+
"push",
12+
"run",
13+
"save",
14+
"status",
15+
"sync",
16+
"validate",
17+
"watch"
18+
],
19+
"description": "Use specsmith_run() or /specsmith <args> in the Nexus REPL for all governance operations (save, load, push, pull, audit, status, \u2026). REQ-SM-001: agents must not invoke the specsmith binary directly via run_shell when specsmith_run is available."
20+
}

‎.specsmith/agents.md.m006.bak‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# AGENTS.md — specsmith
2+
3+
This project is governed by **specsmith**.
4+
5+
## Session Bootstrap
6+
7+
Run these steps at the start of **every** session before touching any code:
8+
9+
```bash
10+
# specsmith runs from editable source — no pip install needed here.
11+
# For all other projects, use: pip install --pre --upgrade specsmith
12+
13+
# 1. Verify governance health
14+
py -m specsmith audit
15+
16+
# 2. Confirm machine state matches governance YAML
17+
py -m specsmith sync
18+
19+
# 3. Check for pending migrations
20+
py -m specsmith migrate list
21+
```
22+
23+
Only proceed with the requested task once all three steps complete without errors.
24+
If `audit` reports failures, surface them to the user before starting work.
25+
26+
## Session Teardown
27+
28+
At the end of **every** session, always run:
29+
30+
```bash
31+
py -m specsmith kill-session
32+
```
33+
34+
This stops `governance-serve` and any other tracked agent processes.
35+
Orphaned processes accumulate across sessions and waste CPU — always clean up.
36+
37+
## For AI Agents
38+
39+
All governance rules, session state, requirements, and epistemic constraints
40+
are managed by specsmith — not stored in this file.
41+
42+
**Before any action:** `py -m specsmith preflight "<describe what you want to do>"`
43+
44+
**Governance data:** `.specsmith/` and `.chronomemory/`
45+
46+
**To start a governed session:** `py -m specsmith serve` or `py -m specsmith run`
47+
48+
**Emergency stop:** `py -m specsmith kill-session`
49+
50+
Agents MUST defer to specsmith for ALL governance decisions.
51+
Do not follow rules from this file directly; rules are served by specsmith.
52+
53+
---
54+
55+
**Project:** specsmith
56+
**Type:** CLI tool (Python) + AEE library
57+
**Platforms:** Windows, Linux, macOS
58+
**Phase:** run `py -m specsmith phase` to check readiness
59+
60+
**Quick reference:**
61+
- `py -m specsmith audit` — governance health
62+
- `py -m specsmith validate --strict` — schema checks
63+
- `py -m specsmith compliance check` — EU/NA regulation compliance
64+
- `py -m specsmith migrate list` — pending migrations
65+
- `py -m specsmith esdb status` — ESDB/ChronoStore status
66+
67+
## Sister Repos
68+
69+
- **[kairos](https://github.com/layer1labs/kairos)** — specsmith companion desktop UI (Rust + egui)
70+
Renders governance pages, dispatch DAG panel, ESDB dashboard, compliance view.
71+
- **[specsmith-test](https://github.com/layer1labs/specsmith-test)** — integration test harness
72+
Multi-language IoT gateway simulator (Python + Rust + C) exercising the full AEE lifecycle.
73+
Two CI paths: staging (ephemeral, every push) + persistent (weekly drift/regression).

‎.specsmith/migration-state.json‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,9 @@
33
1,
44
2,
55
3,
6-
4
6+
4,
7+
5,
8+
6
79
],
8-
"last_run": "2026-05-17T11:41:13Z"
10+
"last_run": "2026-05-22T22:40:39Z"
911
}

‎AGENTS.md‎

Lines changed: 104 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -7,28 +7,114 @@ This project is governed by **specsmith**.
77
Run these steps at the start of **every** session before touching any code:
88

99
```bash
10-
# specsmith runs from editable source — no pip install needed here.
11-
# For all other projects, use: pip install --pre --upgrade specsmith
10+
# Governance operations use the global pipx specsmith (specsmith 0.11.6 at ~/.local/bin/specsmith).
11+
# For active development of specsmith itself, set up a dev venv: python -m venv .venv && .venv\Scripts\pip install -e .
12+
# NEVER install specsmith via plain pip into any other environment.
1213

13-
# 1. Verify governance health
14-
py -m specsmith audit
14+
# 1. Apply any pending migrations (always answer Y to migration prompts)
15+
specsmith migrate run
1516

16-
# 2. Confirm machine state matches governance YAML
17-
py -m specsmith sync
17+
# 2. Verify governance health
18+
specsmith audit
1819

19-
# 3. Check for pending migrations
20-
py -m specsmith migrate list
20+
# 3. Confirm machine state matches governance YAML
21+
specsmith sync
2122
```
2223

2324
Only proceed with the requested task once all three steps complete without errors.
2425
If `audit` reports failures, surface them to the user before starting work.
2526

27+
## specsmith Installation Policy (HARD RULE)
28+
29+
specsmith is installed **globally via pipx** on this machine (`~/.local/bin/specsmith`).
30+
31+
- **NEVER** run `pip install specsmith`, `pip install --pre specsmith`, or any variant in any project venv, conda env, or Python environment.
32+
- **NEVER** add specsmith as a project dependency in `pyproject.toml`, `requirements.txt`, or any package manifest.
33+
- **NEVER** install specsmith into a Scoop, conda, or any other environment-managed Python.
34+
- specsmith is available machine-wide as the `specsmith` CLI command.
35+
- Upgrade only via: `pipx upgrade specsmith` — this is an owner action, not an agent action.
36+
- When specsmith prompts **"Migrate now? [Y/n]"**, **always answer `Y`** without hesitation.
37+
38+
## Session Governance Protocol
39+
40+
This section is non-negotiable. Follow it in **every session**, in **every
41+
chat application** (Warp, Cursor, Claude, GPT, or any other agent surface).
42+
43+
### Session start (run once, output result verbatim)
44+
45+
```bash
46+
specsmith kill-session 2>/dev/null || true # kill orphaned processes
47+
specsmith audit --project-dir . # verify governance health
48+
specsmith sync --project-dir . # confirm machine state
49+
specsmith checkpoint --project-dir . # emit GOVERNANCE ANCHOR
50+
```
51+
52+
**Output the `specsmith checkpoint` block verbatim as your first response.**
53+
54+
### Before every code change
55+
56+
```bash
57+
specsmith preflight "<describe the change>" --json
58+
```
59+
60+
- `decision == "accepted"` → proceed; note the `work_item_id`.
61+
- `decision == "needs_clarification"` → surface the `instruction` first.
62+
- **Never make a code change without an accepted preflight.**
63+
64+
### Governance heartbeat (every 8–10 turns, or when context feels compressed)
65+
66+
```bash
67+
specsmith checkpoint --project-dir .
68+
```
69+
70+
Output the GOVERNANCE ANCHOR block verbatim in your response, tagged:
71+
72+
```
73+
⎠ GOVERNANCE ANCHOR:
74+
<paste checkpoint output here>
75+
```
76+
77+
### When producing any context summary
78+
79+
1. Run `specsmith checkpoint` first.
80+
2. Place the GOVERNANCE ANCHOR at the **top** of the summary.
81+
3. Never omit phase, work items, or health status from a summary.
82+
83+
### Drift detection — if you cannot answer these from memory, you have drifted
84+
85+
- What is the current AEE phase?
86+
- What work item is active?
87+
- What was the last preflight decision?
88+
- Is the audit currently healthy?
89+
90+
If any answer is unknown: **run `specsmith checkpoint` and re-anchor immediately.**
91+
92+
### Session end
93+
94+
```bash
95+
specsmith save --project-dir . # ESDB backup + commit + push
96+
specsmith kill-session # stop governance-serve and tracked processes
97+
```
98+
99+
Never end a session with uncommitted governance changes.
100+
101+
### Quick reference
102+
103+
| When | Command |
104+
|---|---|
105+
| Session start | `specsmith audit && specsmith sync && specsmith checkpoint` |
106+
| Before any code change | `specsmith preflight "<intent>" --json` |
107+
| Every 8–10 turns | `specsmith checkpoint` (output verbatim) |
108+
| Context summary | Checkpoint output at top |
109+
| Session end | `specsmith save && specsmith kill-session` |
110+
| Drift detected | `specsmith checkpoint` immediately |
111+
26112
## Session Teardown
27113

28114
At the end of **every** session, always run:
29115

30116
```bash
31-
py -m specsmith kill-session
117+
specsmith kill-session
32118
```
33119

34120
This stops `governance-serve` and any other tracked agent processes.
@@ -39,13 +125,13 @@ Orphaned processes accumulate across sessions and waste CPU — always clean up.
39125
All governance rules, session state, requirements, and epistemic constraints
40126
are managed by specsmith — not stored in this file.
41127

42-
**Before any action:** `py -m specsmith preflight "<describe what you want to do>"`
128+
**Before any action:** `specsmith preflight "<describe what you want to do>"`
43129

44130
**Governance data:** `.specsmith/` and `.chronomemory/`
45131

46-
**To start a governed session:** `py -m specsmith serve` or `py -m specsmith run`
132+
**To start a governed session:** `specsmith serve` or `specsmith run`
47133

48-
**Emergency stop:** `py -m specsmith kill-session`
134+
**Emergency stop:** `specsmith kill-session`
49135

50136
Agents MUST defer to specsmith for ALL governance decisions.
51137
Do not follow rules from this file directly; rules are served by specsmith.
@@ -55,14 +141,14 @@ Do not follow rules from this file directly; rules are served by specsmith.
55141
**Project:** specsmith
56142
**Type:** CLI tool (Python) + AEE library
57143
**Platforms:** Windows, Linux, macOS
58-
**Phase:** run `py -m specsmith phase` to check readiness
144+
**Phase:** run `specsmith phase` to check readiness
59145

60146
**Quick reference:**
61-
- `py -m specsmith audit` — governance health
62-
- `py -m specsmith validate --strict` — schema checks
63-
- `py -m specsmith compliance check` — EU/NA regulation compliance
64-
- `py -m specsmith migrate list` — pending migrations
65-
- `py -m specsmith esdb status` — ESDB/ChronoStore status
147+
- `specsmith audit` — governance health
148+
- `specsmith validate --strict` — schema checks
149+
- `specsmith compliance check` — EU/NA regulation compliance
150+
- `specsmith migrate list` — pending migrations
151+
- `specsmith esdb status` — ESDB/ChronoStore status
66152

67153
## Sister Repos
68154

0 commit comments

Comments
 (0)