specwright 0.3.1

The architect of agentic workflows. Defines, validates, and executes AIPs.

Specwright

The architect of agentic workflows.

Specwright defines, validates, and executes Agentic Implementation Plans (AIPs) — human-in-the-loop governance for AI-assisted software development.

Specwright defines. Dogfold builds. Gorch orchestrates. LifeOS lives.

---

What is Specwright?

Specwright is a meta-engineering orchestration layer that ensures AI-driven development is:

• Traceable: Every decision logged, every gate validated
• Tiered: Governance scales with risk (Tier A/B/C)
• Human-friendly: Write specs in Markdown, execute validated YAML
• Compliant: Aligned with ISO 42001 and NIST AI RMF

You write the plan. Specwright ensures it's rigorous.

---

🎯 Quick Start

# Install
pip install specwright

# Define a new plan (human-friendly Markdown)
spec new --tier B --title "Add OAuth login" --owner alice --goal "Implement secure authentication"

# Edit the generated Markdown spec
# specs/add-oauth-login.md

# Compile to validated YAML
spec compile specs/add-oauth-login.md

# Validate against schema
spec validate specs/add-oauth-login.compiled.yaml

# Execute with governance
spec run specs/add-oauth-login.compiled.yaml

# Or preview without execution
spec run specs/add-oauth-login.compiled.yaml --plan

---

🌟 The Ecosystem

Specwright is part of a larger experimental toolchain:

Tool	Purpose	Status
Specwright	Defines AIPs, enforces governance	Alpha (v0.3.0)
Dogfold	Recursive Python scaffolding	Experimental
Gorch	Google Cloud orchestration	Future
LifeOS	Personal operating system	Future

Note: All tools in this ecosystem are early-stage and actively evolving. Specwright is functional but should be considered alpha software.

---

📚 Core Concepts

Why Specwright?

The problem: AI tools generate code fast, but lack governance, traceability, and risk management.

The solution: Specwright introduces tiered governance:

Three Risk Tiers

All work follows the same workflow, but governance rigor scales with risk:

Tier	Risk Level	Gates	SLA	Coverage	Use Cases
A	High	5 formal gates	24-72h	90%+	Security/compliance/architecture changes
B	Moderate	5 standard gates	8-48h	85%+	Feature development, refactoring
C	Low	5 fast-lane gates (4 auto-approved)	1-24h	70%+	Documentation, utilities, minor fixes

Key principle: The tiers modulate rigor, not sequence.

Same workflow, different rigor. All tiers follow the canonical 5-gate model:

1. Planning [G0: Plan Approval]
2. Prompt Engineering [G1: Code Readiness]
3. Implementation [G3: Deployment Approval]
4. Testing [G2: Pre-Release]
5. Governance [G4: Post-Implementation]

Human-Friendly Workflow

Write specs in Markdown, execute validated YAML:

specs/                          # Human-authored specifications
├── my-feature.md              # Write here! (Markdown)
└── my-feature.compiled.yaml   # Generated (don't edit)

aips/                          # Validated AIPs ready for execution
└── AIP-2025-10-31-001.yaml    # Promoted from compiled spec

This separation ensures:

• Humans collaborate in Markdown (easy to read/write/review)
• Machines execute YAML (validated, deterministic)
• Git tracks both (spec shows intent, AIP shows execution)

---

🛠️ CLI Commands

spec new

Create a new Markdown specification from tier template.

spec new --tier <A|B|C> --title "Task title" --owner "Your Name" --goal "What we're building"

# Interactive prompts
spec new

# Specify output path
spec new --tier B --title "Add feature" --owner alice --goal "Implement X" --output custom/path.md

Output: Human-editable Markdown spec with:

• YAML frontmatter (tier, title, owner, goal)
• Structured sections (Objective, Context, Plan, etc.)
• Step templates with gates, prompts, commands, outputs

spec compile

Compile Markdown spec to validated YAML AIP.

spec compile specs/my-feature.md

# Specify output path
spec compile specs/my-feature.md --output custom/output.yaml

# Force overwrite if compiled file exists
spec compile specs/my-feature.md --overwrite

What it does:

• Parses Markdown using markdown-it-py (robust token-based parsing)
• Validates frontmatter, sections, plan steps
• Checks output paths are within repo bounds
• Generates canonical YAML with source hash
• Round-trip guard: fails if existing compiled file differs (unless --overwrite)

Output includes:

meta:
  source_md_path: specs/my-feature.md
  source_md_rel: specs/my-feature.md
  source_md_sha256: "abc123..."
  compiler_version: spec-compiler/0.1.0
  compiled_at: null  # intentionally null for determinism
  tier: B
  title: "My Feature"
  # ...

spec validate

Validate AIP against JSON schema with tier defaults merged.

spec validate specs/my-feature.compiled.yaml
spec validate aips/AIP-2025-10-31-001.yaml

What it checks:

• Schema compliance (required fields, types, constraints)
• Tier-specific requirements (coverage targets, gate structure)
• Path safety (no escaping repo root)
• Gate references (G0-G4 only)

spec run

Execute an AIP in guided checklist mode (v0.1).

# Interactive execution
spec run specs/my-feature.compiled.yaml

# Preview mode (no execution)
spec run specs/my-feature.compiled.yaml --plan

What it does (v0.1):

• Displays each step with role, prompts, commands, outputs
• Prompts for manual completion confirmation
• Shows gate checkpoints
• (Future: actual agent execution, state persistence, automated gates)

spec diff

Show semantic diff between Markdown and compiled YAML.

spec diff specs/my-feature.md

# Detailed output
spec diff specs/my-feature.md --verbose

Useful for:

• Catching compilation drift
• Reviewing changes before commit
• Validating round-trip integrity

---

📐 Design Principles

1. Markdown-First Authoring

Humans write in Markdown. Machines execute YAML.

Why Markdown?

• Human-readable and writable
• Great for collaboration (Git diffs, PR reviews)
• Natural section structure (H2/H3 headings)
• Easy to template with Jinja2

Why not edit YAML directly?

• YAML is verbose and error-prone for humans
• Hard to review in PRs
• Machine format should be generated, not authored

2. Deterministic Compilation

Every compilation is reproducible and verifiable:

What it does:

• Canonical YAML ordering: sorted keys, no anchors/aliases
• Source hash tracking: source_md_sha256 for integrity
• Null timestamps: compiled_at: null for bit-identical output
• Round-trip guard: fails if recompiling produces different output

This enables:

• Git-friendly diffs (no spurious changes)
• Pre-commit hooks (enforce MD/YAML sync)
• Audit trails (hash verification)

Compiled YAML includes:

meta:
  source_md_path: specs/user-auth.md
  source_md_sha256: "abc123..."
  compiler_version: "spec-compiler/0.1.0"
  compiled_at: null  # intentionally null for determinism
  tier: "B"

3. Governance as Code

AIPs aren't just checklists — they're executable governance contracts:

• Schema-validated (JSON Schema)
• Tier-aware defaults
• Gate approvals enforced
• Metrics tracked (coverage, defects, budget)

4. Token-Based Markdown Parsing

Uses markdown-it-py instead of regex:

• Handles nested code blocks correctly
• Robust against edge cases (backticks in headings, etc.)
• Proper token tree for precise extraction
• Extensible for future enhancements

5. Tiered Governance, Not Tiered Workflows

Same workflow for all tiers, different governance:

• Tier A: All gates require human approval (24-72h SLAs)
• Tier B: Standard approval process (8-48h SLAs)
• Tier C: Most gates auto-approved (1-24h SLAs, only G2 requires human)

This ensures:

• Process integrity (no skipped steps)
• Flexibility (adjust rigor to risk)
• Auditability (all tiers traceable)

6. Schema Validation with Defaults Merging

AIPs can be sparse (only specify what differs from tier defaults):

# In your compiled AIP (minimal)
meta:
  tier: B
  title: "My Feature"
# ...

# At validation time, merged with tier-B defaults:
gates:
  - gate_id: G0-plan-approval
    approver_role: "Tech Lead + Peer"
    # ... all default gate config

This keeps specs concise while ensuring complete validation.

---

📖 Learn More

• Agentsway Implementation Guide - Core principles and governance framework
• Getting Started - 5-minute walkthrough
• Templates - Tier-specific Markdown templates
• Schema - JSON Schema for AIP validation
• Defaults - Tier-specific default configurations
• Contributing - How to contribute to Specwright

---

🏗️ Project Structure

specwright/
├── src/spec/                    # Core implementation
│   ├── cli/spec.py             # CLI commands
│   ├── compiler/               # Markdown→YAML compiler
│   │   ├── parser.py           # Token-based MD parser
│   │   └── compiler.py         # Deterministic YAML generator
│   └── core/                   # Shared utilities
│       └── loader.py           # YAML loading + defaults merging
│
├── config/                      # Configuration
│   ├── templates/
│   │   ├── specs/              # Markdown templates (tier-a/b/c)
│   │   └── aips/               # YAML templates (legacy)
│   ├── defaults/               # Tier defaults (tier-A/B/C.yaml)
│   ├── schemas/                # JSON Schema for validation
│   └── policies/               # Reusable policy packs
│
├── specs/                       # Human-authored Markdown specs
├── aips/                        # Validated AIPs (YAML)
├── docs/                        # Documentation
├── tests/                       # Test suite
│   ├── compiler/
│   │   └── golden/             # Golden test snapshots
│   └── integration/
│
├── pyproject.toml              # Project configuration
└── README.md                   # This file

---

🧪 Testing

# Run linter
ruff check src/ tests/

# Type checking
mypy src/

# Unit tests
pytest tests/

# Golden tests (snapshot-based)
pytest tests/compiler/golden/ -v

# Integration tests
pytest tests/integration/ -v

Pre-commit Hook

Enforce MD/YAML sync:

# .git/hooks/pre-commit
#!/bin/bash
for md in specs/*.md; do
    yaml="${md%.md}.compiled.yaml"
    if [ -f "$yaml" ]; then
        spec diff "$md" || exit 1
    fi
done

---

🔄 Workflow Example

1. Create a Tier B feature spec

spec new --tier B --title "Add OAuth login" --owner alice --goal "Implement Google OAuth"

Generated: specs/add-oauth-login.md

2. Edit the spec

---
tier: B
title: Add OAuth login
owner: alice
goal: Implement Google OAuth
---

# Add OAuth login

## Objective

Add Google OAuth 2.0 authentication flow to allow users to sign in with their Google accounts.

## Acceptance Criteria

- [ ] Users can click "Sign in with Google"
- [ ] OAuth callback handles authorization code
- [ ] User profile synced to local database
- [ ] Session management with JWT
- [ ] 85% test coverage achieved

## Context

### Background

Current email/password auth is limiting adoption. Users expect social login.

### Constraints

- Must use Google's official OAuth 2.0 library
- Store only necessary user data (email, name, profile picture)
- GDPR compliant (user can revoke access)

## Plan

### Step 1: Planning [G0: Plan Approval]

**Prompt:**

Create detailed WBS for OAuth integration:
- Frontend: Google Sign-In button + callback page
- Backend: OAuth flow, token exchange, user provisioning
- Database: user table updates for OAuth identifiers
- Security: CSRF protection, state validation

**Outputs:**

- `artifacts/plan/wbs.md`
- `artifacts/plan/security-checklist.md`

### Step 2: Prompt Engineering [G1: Code Readiness]

**Prompt:**

Generate implementation prompts for:
- Frontend: React component with Google OAuth SDK
- Backend: FastAPI endpoints for /auth/google/callback
- Database migrations for oauth_provider, oauth_id fields

**Outputs:**

- `artifacts/prompts/frontend-prompts.md`
- `artifacts/prompts/backend-prompts.md`

### Step 3: Implementation [G3: Deployment Approval]

**Commands:**

```bash
ruff .
mypy .
pytest -q

Outputs:

• artifacts/code/release-notes.md
• artifacts/code/runbook.md

Step 4: Testing [G2: Pre-Release]

Commands:

pytest --cov=src --cov-report=xml

Outputs:

• artifacts/test/coverage.xml

Step 5: Governance [G4: Post-Implementation]

Outputs:

• artifacts/governance/decision-log.md
• artifacts/governance/privacy-checklist.md

Models & Tools

Tools: bash, pytest, ruff, mypy

Repository

Branch: feat/add-oauth-login

Merge Strategy: squash

### 3. Compile and validate

```bash
spec compile specs/add-oauth-login.md
spec validate specs/add-oauth-login.compiled.yaml

4. Execute

# Interactive guided execution
spec run specs/add-oauth-login.compiled.yaml

# Or preview first
spec run specs/add-oauth-login.compiled.yaml --plan

5. Promote to AIP (optional)

spec promote specs/add-oauth-login.md --to aips/

Output: aips/AIP-2025-10-31-001.yaml (immutable release artifact)

---

🎓 Learning Resources

For New Users

1. Read Agentsway Implementation Guide
2. Try creating a Tier C spec: spec new --tier C
3. Review the generated Markdown template
4. Compile and run through the workflow

For Contributors

1. Read Spec Compilation Guide
2. Review compiler implementation
3. Run golden tests: pytest tests/compiler/golden/ -v
4. Check open issues

---

🎨 The Story

Specwright was built to solve a real problem: How do you govern AI-driven development without crushing velocity?

The answer: Tiered governance. Not every change needs a 72-hour review cycle. Documentation updates can fast-lane with auto-approved gates. Security changes get formal sign-offs.

Specwright ensures the right rigor for the right risk.

It's part of a larger ecosystem:

• Specwright defines the governance framework
• Dogfold learns from builds and scaffolds recursively
• Gorch orchestrates on Google Cloud
• LifeOS presents it all to humans

This is meta-engineering: tools that build the builders, then build the world.

---

🚀 Roadmap

v0.3.0 (Current)

• ✅ Markdown-first authoring with Jinja2 templates
• ✅ Deterministic compilation with source hash tracking
• ✅ Token-based Markdown parsing
• ✅ Round-trip validation and diff detection
• ✅ Tier-specific governance with 5-gate model
• ✅ Schema validation with defaults merging

v0.4.0 (Next Quarter)

• Rename to specwright package
• Actual agent execution (replace checklist mode)
• State persistence (.aip_artifacts/state.json)
• Automated gate approvals (Slack/email integration)
• Metrics tracking (budget, coverage, time-to-green)
• Integration with Dogfold scaffolding

v1.0.0 (Future)

• Multi-agent orchestration
• Policy enforcement engine
• Compliance reporting (ISO 42001, NIST AI RMF)
• Web UI for spec management
• Full Gorch integration (Google Cloud orchestration)

---

🤝 Contributing

Contributions welcome! Please:

1. Read CONTRIBUTING.md for contribution guidelines
2. See DEVELOPMENT.md for local development workflow (dogfooding while building)
3. Check open issues
4. Submit PRs against main branch
5. Ensure tests pass: pytest tests/
6. Run linter: ruff check src/

---

📄 License

MIT License - see LICENSE file for details.

---

🙏 Acknowledgments

• Agentsway Implementation Guide - Governance framework foundation
• ISO 42001:2023 - AI management system standards
• NIST AI RMF 1.0 - Risk management framework
• Dogfold - Recursive scaffolding partner
• Gorch - Google Cloud orchestration layer

---

💬 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]

---

Built with ❤️ for rigorous, traceable, human-in-the-loop AI-assisted development.

Specwright defines. Dogfold builds. Gorch orchestrates. LifeOS lives.