Skip to content

Commit aa2d82d

Browse files
tbitcsoz-agent
tbitcs
and
oz-agent
committed
feat: apply specsmith to itself + community sections + bootstrap docs
- Run specsmith upgrade --full on specsmith repo (dogfooding) - Generate all modular governance files (SESSION-PROTOCOL.md, LIFECYCLE.md, etc.) - Strengthen community support section (tell friends, report bugs, suggest features, write about us) - Add 'The specsmith Bootstrap' section explaining self-governance - Reset scaffold.yml to v0.3.6 Co-Authored-By: Oz <oz-agent@warp.dev>
1 parent 5eaba4b commit aa2d82d

24 files changed

Lines changed: 794 additions & 108 deletions

‎.editorconfig‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# EditorConfig — https://editorconfig.org
2+
root = true
3+
4+
[*]
5+
charset = utf-8
6+
end_of_line = lf
7+
insert_final_newline = true
8+
trim_trailing_whitespace = true
9+
indent_style = space
10+
indent_size = 4
11+
12+
[*.py]
13+
indent_size = 4
14+
max_line_length = 100
15+
16+
[*.{yml,yaml}]
17+
indent_size = 2
18+
19+
[*.md]
20+
trim_trailing_whitespace = false
21+
22+
[Makefile]
23+
indent_style = tab
24+
25+
[*.{cmd,bat}]
26+
end_of_line = crlf
27+
28+
[*.{ps1,psm1}]
29+
end_of_line = crlf

‎.github/workflows/ci.yml‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@ name: CI
22

33
on:
44
push:
5-
branches: [main, develop]
5+
branches: [main]
66
pull_request:
7-
branches: [main, develop]
7+
branches: [main]
88

99
concurrency:
1010
group: ci-${{ github.ref }}
@@ -22,9 +22,9 @@ jobs:
2222
with:
2323
python-version: "3.12"
2424
cache: pip
25-
- run: pip install ruff
26-
- run: ruff check src/ tests/
27-
- run: ruff format --check src/ tests/
25+
- run: pip install -e ".[dev]"
26+
- run: ruff check
27+
- run: ruff format --check .
2828

2929
typecheck:
3030
runs-on: ubuntu-latest
@@ -62,6 +62,6 @@ jobs:
6262
with:
6363
python-version: "3.12"
6464
cache: pip
65-
- run: pip install pip-audit
6665
- run: pip install -e .
66+
- run: pip install pip-audit
6767
- run: pip-audit

‎.github/workflows/dev-release.yml‎

Lines changed: 28 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -9,29 +9,8 @@ permissions:
99
contents: read
1010

1111
jobs:
12-
test:
12+
dev-build:
1313
runs-on: ubuntu-latest
14-
# Only run from the develop branch — blocks accidental workflow_dispatch from main.
15-
if: github.ref == 'refs/heads/develop'
16-
steps:
17-
- uses: actions/checkout@v6
18-
- uses: actions/setup-python@v6
19-
with:
20-
python-version: "3.12"
21-
cache: pip
22-
- run: pip install -e ".[dev]"
23-
- run: ruff check src/ tests/
24-
- run: ruff format --check src/ tests/
25-
- run: mypy src/specsmith --ignore-missing-imports
26-
- run: pytest tests/ -x -q
27-
28-
build-and-publish:
29-
needs: test
30-
runs-on: ubuntu-latest
31-
environment: pypi
32-
permissions:
33-
contents: read
34-
id-token: write
3514
steps:
3615
- uses: actions/checkout@v6
3716
with:
@@ -47,84 +26,37 @@ jobs:
4726

4827
- name: Set dev version
4928
run: |
50-
# Use pyproject.toml version as the base (no patch bump).
51-
# pyproject.toml should always hold the NEXT release version (e.g. 0.3.0).
52-
# Dev builds publish as 0.3.0.devN — PEP 440 pre-release of the upcoming release.
53-
# N = total commit count (monotonically increasing, unique per push).
54-
BASE_VERSION=$(grep 'version = ' pyproject.toml | head -1 | sed 's/version = "\(.*\)"/\1/')
55-
COMMIT_COUNT=$(git rev-list --count HEAD)
56-
DEV_VERSION="${BASE_VERSION}.dev${COMMIT_COUNT}"
57-
echo "DEV_VERSION=${DEV_VERSION}" >> $GITHUB_ENV
58-
59-
# Patch pyproject.toml with dev version
60-
sed -i "s/version = \"${BASE_VERSION}\"/version = \"${DEV_VERSION}\"/" pyproject.toml
61-
echo "Building version: ${DEV_VERSION}"
29+
BASE=$(grep 'version = ' pyproject.toml | head -1 | sed 's/version = "\(.*\)"//')
30+
MAJOR=$(echo $BASE | cut -d. -f1)
31+
MINOR=$(echo $BASE | cut -d. -f2)
32+
PATCH=$(echo $BASE | cut -d. -f3)
33+
NP=$((PATCH + 1))
34+
TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo HEAD~100)
35+
NC=$(git rev-list --count HEAD ^$TAG 2>/dev/null || echo 0)
36+
DV="${MAJOR}.${MINOR}.${NP}.dev${NC}"
37+
echo "DEV_VERSION=${DV}" >> $GITHUB_ENV
38+
sed -i "s/version = "${BASE}"/version = "${DV}"/" pyproject.toml
39+
echo "Building version: ${DV}"
6240
6341
- run: python -m build
6442

65-
- name: Publish dev release to PyPI
66-
uses: pypa/gh-action-pypi-publish@release/v1
67-
continue-on-error: true # version already exists on PyPI is not a failure
43+
- name: Upload build artifacts
44+
uses: actions/upload-artifact@v7
45+
with:
46+
name: dev-dist
47+
path: dist/
6848

69-
docs-build:
70-
needs: build-and-publish
49+
pypi-dev-publish:
50+
needs: dev-build
7151
runs-on: ubuntu-latest
52+
environment: pypi
53+
permissions:
54+
id-token: write
7255
continue-on-error: true
7356
steps:
74-
- name: Trigger ReadTheDocs builds (develop + latest)
75-
env:
76-
RTD_TOKEN: ${{ secrets.RTD_TOKEN }}
77-
run: |
78-
if [ -z "$RTD_TOKEN" ]; then
79-
echo "WARNING: RTD_TOKEN secret is not set. Skipping RTD build trigger."
80-
echo "To fix: go to GitHub repo Settings → Secrets → Actions and add RTD_TOKEN."
81-
echo "Get the token from: https://readthedocs.org/accounts/tokens/"
82-
exit 0
83-
fi
84-
85-
# Trigger the 'develop' RTD version build (accessible at /en/develop/)
86-
echo "Triggering RTD build for 'develop' version..."
87-
STATUS=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
88-
-H "Authorization: Token $RTD_TOKEN" \
89-
"https://readthedocs.org/api/v3/projects/specsmith/versions/develop/builds/")
90-
echo "RTD develop build trigger: HTTP $STATUS"
91-
if [ "$STATUS" != "202" ]; then
92-
echo "WARNING: RTD develop build trigger returned HTTP $STATUS (expected 202)."
93-
echo "Common causes:"
94-
echo " - 401: RTD_TOKEN is invalid or expired"
95-
echo " - 404: 'develop' version not activated in RTD dashboard"
96-
echo " Fix: https://readthedocs.org/projects/specsmith/versions/ → activate 'develop'"
97-
fi
98-
99-
# Step 1: Set RTD project default_branch to 'develop'
100-
echo "[1/3] Setting RTD project default_branch to 'develop'..."
101-
PATCH_STATUS=$(curl -s -o /dev/null -w "%{http_code}" -X PATCH \
102-
-H "Authorization: Token $RTD_TOKEN" \
103-
-H "Content-Type: application/json" \
104-
-d '{"default_branch": "develop"}' \
105-
"https://readthedocs.org/api/v3/projects/specsmith/")
106-
echo "RTD project PATCH: HTTP $PATCH_STATUS"
107-
108-
# Step 2: Set the 'latest' VERSION object's identifier to 'develop'
109-
# This is the key step — the version object has its own branch setting
110-
# separate from the project-level default_branch.
111-
echo "[2/3] Setting RTD 'latest' version identifier to 'develop'..."
112-
VER_PATCH=$(curl -s -o /tmp/ver_patch.txt -w "%{http_code}" -X PATCH \
113-
-H "Authorization: Token $RTD_TOKEN" \
114-
-H "Content-Type: application/json" \
115-
-d '{"identifier": "develop", "active": true}' \
116-
"https://readthedocs.org/api/v3/projects/specsmith/versions/latest/")
117-
echo "RTD 'latest' version PATCH: HTTP $VER_PATCH"
118-
cat /tmp/ver_patch.txt | head -c 200 || true
119-
120-
# Step 3: Trigger a fresh /en/latest/ build (now tracks develop)
121-
echo "[3/3] Triggering RTD 'latest' build from develop..."
122-
LATEST_STATUS=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
123-
-H "Authorization: Token $RTD_TOKEN" \
124-
"https://readthedocs.org/api/v3/projects/specsmith/versions/latest/builds/")
125-
echo "RTD latest build trigger: HTTP $LATEST_STATUS"
126-
if [ "$LATEST_STATUS" != "202" ]; then
127-
echo "WARNING: RTD latest trigger returned HTTP $LATEST_STATUS"
128-
echo "If 404: 'latest' version may not be active in RTD dashboard."
129-
echo "Fix: https://readthedocs.org/projects/specsmith/versions/ -> activate 'latest'"
130-
fi
57+
- uses: actions/download-artifact@v8
58+
with:
59+
name: dev-dist
60+
path: dist/
61+
- name: Publish dev release to PyPI
62+
uses: pypa/gh-action-pypi-publish@release/v1

‎.specsmith/credit-budget.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"monthly_cap_usd": 0.0,
3+
"alert_threshold_pct": 80,
4+
"alert_watermarks_usd": [
5+
5.0,
6+
10.0,
7+
25.0,
8+
50.0
9+
],
10+
"enabled": true,
11+
"enforcement_mode": "soft"
12+
}

‎.specsmith/ledger-chain.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
5a6995207163ba49b823fda0bfbcf4cd29e1e2184a07064db193fdf634617d64
22
30255640fa4f54c2946a841ad9612a1f69a9092f368728ecde0e01fa1ac92c09
3+
45890fddd2d612334ab9bfff9da620278331b0d6994abddaea605ee0c4309560

‎.warp/skills/SKILL.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# specsmith — Governed Project Skill
2+
3+
## Context
4+
This project follows the Agentic AI Development Workflow Specification (v0.3.7.dev2).
5+
Project type: CLI tool (Python) (Section 17.3).
6+
Description: Applied Epistemic Engineering toolkit for AI-assisted development..
7+
8+
## Session Start
9+
1. Read `AGENTS.md` — the governance hub
10+
2. Read `LEDGER.md` — check last session state and open TODOs
11+
3. Read `docs/governance/RULES.md` — hard rules and stop conditions
12+
13+
## Workflow
14+
All changes follow: **propose → check → execute → verify → record**.
15+
- Every code change requires a proposal in the ledger
16+
- Every proposal needs verification before marking complete
17+
- Never skip the ledger entry
18+
19+
## Key Files
20+
- `AGENTS.md` — governance hub (read first)
21+
- `LEDGER.md` — session ledger (read second)
22+
- `docs/governance/` — modular governance docs (load on demand)
23+
- `docs/REQUIREMENTS.md` — formal requirements
24+
- `docs/TEST_SPEC.md` — test specifications
25+
- `docs/ARCHITECTURE.md` — system architecture
26+
27+
## Session Start
28+
Before any work, run: `specsmith update --check --project-dir .`
29+
If outdated, run: `specsmith update --yes`
30+
31+
## Commands
32+
When user says `commit`: run `specsmith commit --project-dir .`
33+
When user says `push`: run `specsmith push --project-dir .`
34+
When user says `sync`: run `specsmith sync --project-dir .`
35+
When user says `pr`: run `specsmith pr --project-dir .`
36+
When user says `audit`: run `specsmith audit --project-dir .`
37+
When user says `session-end`: run `specsmith session-end --project-dir .`
38+
39+
## Verification
40+
Before marking any task complete, run: ruff check, pytest, mypy
41+
42+
## Credit Tracking
43+
After completing tasks, record token usage:
44+
```
45+
specsmith credits record --model <model> --provider <provider> --tokens-in <N> --tokens-out <N> --task "<desc>"
46+
```
47+
Check budget: `specsmith credits summary`
48+
49+
## Rules
50+
- Proposals before changes (no exceptions)
51+
- Verify before recording completion
52+
- Use execution shims (`scripts/exec.cmd` / `scripts/exec.sh`) for external commands
53+
- Keep AGENTS.md under 200 lines
54+
- Record every session in the ledger
55+
- Record credit usage at session end

‎CLAUDE.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# CLAUDE.md
2+
3+
This project follows the Agentic AI Development Workflow Specification (v0.3.7.dev2).
4+
Project type: CLI tool (Python). Description: Applied Epistemic Engineering toolkit for AI-assisted development..
5+
6+
## Start here
7+
1. Read `AGENTS.md` for project identity, governance hub, and file registry
8+
2. Read `LEDGER.md` for session state and open TODOs
9+
3. Read `docs/governance/RULES.md` for hard rules
10+
11+
## Workflow
12+
All changes follow: propose → check → execute → verify → record.
13+
Never modify code without a proposal in the ledger first.
14+
15+
## Project type
16+
CLI tool (Python) (Spec Section 17.3)
17+
18+
## Key constraints
19+
- AGENTS.md is the governance hub — keep it under 200 lines
20+
- Modular governance docs live in `docs/governance/`
21+
- All agent-invoked commands must have timeouts
22+
- Use `scripts/exec.cmd` or `scripts/exec.sh` for bounded execution
23+
- Record every session in LEDGER.md
24+
25+
## Verification
26+
Before marking any task complete, run: ruff check, pytest, mypy
27+
28+
## Session Start
29+
Before any work, run: `specsmith update --check --project-dir .`
30+
If outdated, run: `specsmith update --yes`
31+
32+
## Commands
33+
When user says `commit`: run `specsmith commit --project-dir .`
34+
When user says `push`: run `specsmith push --project-dir .`
35+
When user says `sync`: run `specsmith sync --project-dir .`
36+
When user says `pr`: run `specsmith pr --project-dir .`
37+
When user says `audit`: run `specsmith audit --project-dir .`
38+
When user says `session-end`: run `specsmith session-end --project-dir .`
39+
40+
## Credit Tracking
41+
At session end, record token usage:
42+
`specsmith credits record --model <model> --provider anthropic --tokens-in <N> --tokens-out <N> --task "<desc>"`
43+
Check budget: `specsmith credits summary`

‎CODE_OF_CONDUCT.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
6+
7+
## Our Standards
8+
9+
Examples of behavior that contributes to a positive environment:
10+
11+
- Using welcoming and inclusive language
12+
- Being respectful of differing viewpoints and experiences
13+
- Gracefully accepting constructive criticism
14+
- Focusing on what is best for the community
15+
- Showing empathy towards other community members
16+
17+
Examples of unacceptable behavior:
18+
19+
- Trolling, insulting/derogatory comments, and personal or political attacks
20+
- Public or private harassment
21+
- Publishing others' private information without explicit permission
22+
- Other conduct which could reasonably be considered inappropriate in a professional setting
23+
24+
## Enforcement
25+
26+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers. All complaints will be reviewed and investigated promptly and fairly.
27+
28+
## Attribution
29+
30+
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

‎LEDGER.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -197,3 +197,9 @@ Begin glossa-lab integration — AEESession for Indus hypothesis tracking. Separ
197197
### Open TODOs
198198
- [ ] Add action button in VS Code session chat when agent finds a fixable issue
199199
- [ ] Add VCS status live refresh (currently only at session start)
200+
201+
## 2026-04-09T08:43 — specsmith migration: 0.3.0 → 0.3.6.dev178
202+
- **Author**: specsmith
203+
- **Type**: migration
204+
- **Status**: complete
205+
- **Chain hash**: `45890fddd2d61233...`

‎README.md‎

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -159,12 +159,15 @@ The **specsmith AEE Workbench** VS Code extension is the flagship client:
159159

160160
## Supporting specsmith
161161

162-
If specsmith is saving you time or helping your team ship better software, please consider:
162+
specsmith is open source and built by a small team. Every bit of support helps:
163163

164-
- **[Sponsoring BitConcepts](https://github.com/sponsors/BitConcepts)** — directly funds development
165-
- **Starring** [specsmith](https://github.com/BitConcepts/specsmith) and [specsmith-vscode](https://github.com/BitConcepts/specsmith-vscode) on GitHub
166-
- **Reporting bugs** and **requesting features** via [GitHub Issues](https://github.com/BitConcepts/specsmith/issues)
167-
- **Contributing** — see [CONTRIBUTING.md](CONTRIBUTING.md)
164+
- ⭐ **Star** [specsmith](https://github.com/BitConcepts/specsmith) and [specsmith-vscode](https://github.com/BitConcepts/specsmith-vscode) on GitHub
165+
- 📣 **Tell your friends and colleagues** — word of mouth is our best marketing
166+
- 🐛 **Report bugs** via [GitHub Issues](https://github.com/BitConcepts/specsmith/issues) — even small ones help
167+
- 💡 **Suggest features** via [GitHub Discussions](https://github.com/BitConcepts/specsmith/discussions) — we read every suggestion
168+
- 🔧 **Fix bugs and contribute** — see [CONTRIBUTING.md](CONTRIBUTING.md); PRs welcome
169+
- 📝 **Write about specsmith** — blog posts, tutorials, and talks help the community grow
170+
- ❤️ **[Sponsor BitConcepts](https://github.com/sponsors/BitConcepts)** — directly funds development
168171

169172
---
170173

@@ -279,6 +282,13 @@ Use cases: linguistics research, compliance pipelines, AI alignment, patent pros
279282

280283
---
281284

285+
## The specsmith Bootstrap
286+
287+
specsmith governs itself — the specsmith repo is a specsmith-managed project. Run `specsmith audit`
288+
in this repo to check its governance health. This means every feature we add to specsmith is
289+
immediately dogfooded on specsmith itself. The [VS Code extension](https://github.com/BitConcepts/specsmith-vscode)
290+
is developed alongside it as the flagship client.
291+
282292
## Documentation
283293

284294
**[specsmith.readthedocs.io](https://specsmith.readthedocs.io)** — Full manual: AEE primer,

0 commit comments

Comments
 (0)