SpecNative — how to work with this framework

MCP server — v0.7

.specnative/specnative_mcp.py exposes the repository as MCP resources, tools, and prompts so any agent works spec-first without navigating files manually. Installed automatically with its own venv. Supports stdio and SSE transport.

Quick setup — Claude Code

# Add via CLI (from project root)
claude mcp add specnative \
  "$(pwd)/.specnative/.venv/bin/python3" \
  "$(pwd)/.specnative/specnative_mcp.py" \
  -- --repo "$(pwd)"

# Or add to .claude/mcp_settings.json
{
  "mcpServers": {
    "specnative": {
      "command": "/your/project/.specnative/.venv/bin/python3",
      "args": ["/your/project/.specnative/specnative_mcp.py",
               "--repo", "/your/project"]
    }
  }
}

Resources

Tools — query

Tools — multi-agent continuity

Tools — project definition

Tools — archetypes (v0.7)

Tools — templates (v0.7)

Prompts

Full configuration for OpenCode, Claude Desktop, Codex, and SSE transport: .specnative/MCP.md

Repository structure

repo/
├── AGENTS.md              # Meta-index: what is SpecNative, MCP reference — read first
├── spec-native/
│   ├── README.md          # Context folder navigation index
│   ├── PRODUCT.md         # Problem, users, goals (permanent)
│   ├── ARCHITECTURE.md    # System structure and boundaries
│   ├── STACK.md           # Tech stack and version constraints
│   ├── CONVENTIONS.md     # Code rules, naming, testing
│   ├── COMMANDS.md        # Project dev/test/build commands only
│   ├── DECISIONS.md       # Persistent decisions and trade-offs
│   ├── ROADMAP.md         # Temporal direction, no implementation
│   ├── TRACEABILITY.md    # Links between artifacts
│   ├── SESSION.md         # Active work state (multi-agent continuity)
│   ├── specs/
│   │   └── <initiative>/SPEC.md
│   ├── tasks/
│   │   └── <initiative>/TASKS.md
│   ├── workflows/
│   │   ├── PLANNING.md
│   │   ├── IMPLEMENTATION.md
│   │   └── REVIEW.md
│   └── pipelines/
│       ├── CI.md          # Automated validation gates
│       └── CD.md          # Delivery process and environments
├── .claude/commands/      # Slash commands: /spec-init /spec-update /spec-status /spec-handoff
├── codex.toml             # Codex CLI prompt commands
├── opencode.json          # OpenCode MCP + commands + instructions
└── .specnative/
    ├── SCHEMA.md           # Framework contract (not project content)
    ├── MCP.md              # MCP server configuration per agent
    ├── specnative_mcp.py   # MCP server (installed automatically)
    ├── archetypes/         # Custom archetypes (user-defined)
    │   └── README.md
    └── templates/          # Reusable spec templates + decision snippets
        ├── specs/          # Spec templates (.md with +++ front matter)
        └── decisions/      # Decision snippets (.md with +++ front matter)

Files in uppercase are context for agents. README.md files are navigation indexes, not the source of truth. Load the minimum context needed for the current task. SESSION.md persists active work state across agents.

Document ownership — one truth per document

Each document owns one semantic domain. Never duplicate information across files. Update the source of truth, not a parallel summary. All documents live under spec-native/.

Decision test — where to write something

How to generate the full template

Follow these steps in order when helping a user create a SpecNative repository from scratch. Each step populates one document with the right scope.

1. Bootstrap the structure

   Run python3 install.py --target /path/to/repo --profile team. This creates all required folders, placeholder files, agent commands, and configures opencode.json and codex.toml automatically.

2. Initialize project context — guided

   Use /spec-init (Claude Code), spec-init prompt (OpenCode/Codex), or python3 specnative.py init (CLI without agent). The wizard interviews the developer and fills all five core documents.

3. Fill spec-native/PRODUCT.md

   Problem (what friction exists and for whom), Users (segments, needs, context), Goals (measurable outcomes), Non-goals (explicit exclusions), Differential value. Use refine_document('product', …) to update via MCP.

4. Fill spec-native/ARCHITECTURE.md

   System modules and their responsibilities, module boundaries and data flows, key architectural constraints. No implementation detail.

5. Fill spec-native/STACK.md

   Languages and runtimes with exact versions, frameworks and libraries, infrastructure and tooling, constraints and prohibited technologies.

6. Fill spec-native/CONVENTIONS.md

   Naming conventions (files, classes, variables), code style and formatting rules, testing approach (unit / integration / e2e), commit and PR conventions.

7. Fill spec-native/COMMANDS.md

   Actual project commands only: build, test, lint, run/start, migrations. Never include framework CLI commands here.

8. Fill spec-native/ROADMAP.md

   Current priorities in order with rationale. Rough time horizon. No implementation detail, no spec content.

9. Create spec-native/specs/<initiative>/SPEC.md

   ID, state, owner, creation/update dates. Summary, problem, objective. Scope (includes / excludes). Functional and non-functional requirements. Acceptance criteria (Given / When / Then). Dependencies and risks. Execution plan. Validation plan. Use MCP prompt start_initiative().

10. Derive spec-native/tasks/<initiative>/TASKS.md

    One task per implementable unit. Each task: ID, state, owner, dependencies, expected files, observable close criteria, validation command. Use MCP prompt plan_tasks().

11. Record decisions in spec-native/DECISIONS.md

    Only persistent trade-offs that future initiatives must respect. Format: DEC-XXXX, date, state, context, decision, consequences, replaces. Use MCP tool log_decision() for quick inline recording.

12. Fill spec-native/pipelines/CI.md and pipelines/CD.md

    CI: platform, triggers, mandatory and optional gates, failure policy. CD: environments, release process, promotion gates, rollback process.

13. Use checkpoint() at each session pause

    Call checkpoint(initiative, task_id, intent, next_steps) before ending any session. The next agent — regardless of tool — calls resume() to continue exactly from here.

14. Update spec-native/TRACEABILITY.md when an initiative closes

    Link spec → tasks → decisions → main artifacts → validation evidence. Update at close, not during execution. Use MCP prompt close_initiative().

Agent workflow (from AGENTS.md)

1. Check for active session

   Call resume() — if SESSION.md state is not idle, read what the previous agent left and continue from there.

2. Load minimum context

   Call context_snapshot() for a full dump, or read individual docs via read_context().

3. Check spec-native/ROADMAP.md

   Confirm the initiative aligns with current project direction before creating a spec.

4. Read spec-native/DECISIONS.md

   Respect persistent trade-offs that condition the current design.

5. Review or create a SPEC.md in spec-native/specs/

   Use MCP prompt start_initiative() for new initiatives.

6. Derive or read tasks in spec-native/tasks/

   Follow spec-native/workflows/PLANNING.md or use MCP prompt plan_tasks().

7. Implement following spec-native/workflows/IMPLEMENTATION.md

   Use update_task() to mark tasks in_progress and done. Verify CI gates from spec-native/pipelines/CI.md.

8. Record persistent trade-offs with log_decision()

   Only if the decision must survive beyond the current initiative.

9. Checkpoint before pausing

   Call checkpoint(initiative, task_id, intent, next_steps) before every session end.

10. Update TRACEABILITY.md at initiative close

    Link all related artifacts. Use MCP prompt close_initiative().

Required states

SESSION.md

Updated by checkpoint() and handoff(). Reset to idle by close_initiative().

Specs

Tasks

Decisions

Optional TOML metadata

TOML blocks are optional. The base contract is documentary — documents are valid without TOML. Add TOML blocks when you want validate, status, and export CLI commands to work automatically. Place the block near the top of the file. SESSION.md uses +++ TOML front matter (not a ```toml block).

Spec header (spec-native/specs/**/SPEC.md)

```toml
artifact_type = "spec"
id            = "SPEC-0001"
state         = "draft"
owner         = "team-name"
created_at    = "YYYY-MM-DD"
updated_at    = "YYYY-MM-DD"
replaces      = "none"
related_tasks       = ["TASK-0001"]
related_decisions   = ["DEC-0001"]
artifacts           = ["src/example/*"]
validation          = ["pytest", "manual walkthrough"]
```

Task file header (spec-native/tasks/**/TASKS.md)

```toml
artifact_type = "task_file"
initiative    = "initiative-name"
spec_id       = "SPEC-0001"
owner         = "team-name"
state         = "todo"
```

Individual task block

```toml
id             = "TASK-0001"
title          = "Task title"
state          = "todo"
owner          = "team-name"
dependencies   = []
expected_files = ["src/example.py"]
close_criteria = "Observable closure condition"
validation     = ["pytest tests/example_test.py"]
```

CLI reference

tools/specnative.py — invoke it from the project root. Use init and update when no agent is available.

# Interactive project setup (no agent needed)
python3 specnative.py init

# Detect gaps and refine iteratively
python3 specnative.py update
python3 specnative.py update --doc stack

# Show spec and task state overview
python3 specnative.py status

# Validate required files and TOML consistency
python3 specnative.py validate

# Export full index
python3 specnative.py export-index --output exports/index.json

Archetypes & templates (via MCP tools)

# List available archetypes (built-in + local)
list_archetypes()

# Preview an archetype before applying
read_archetype('java-hexagonal')

# Apply to spec-native/ (skips filled docs)
apply_archetype('java-hexagonal')
apply_archetype('java-hexagonal', force=True)   # overwrite all

# List templates
list_templates()                  # both spec + decision
list_templates('spec')
list_templates('decision')

# Create SPEC.md from template
apply_spec_template('feature-rest-endpoint', 'user-auth')

# Append decision to DECISIONS.md (auto DEC-XXXX)
apply_decision_snippet('jwt-authentication')

Built-in archetypes

Built-in spec templates

Built-in decision snippets

Standalone installer

install.py bootstraps SpecNative from a GitHub release with no dependencies beyond the Python standard library. Installs agent commands, configures opencode.json and codex.toml, and sets up the MCP venv.

# Minimal — AI context layer only
curl -sSL https://github.com/rafex/SpecNative-Development/releases/latest/download/install.py \
  | python3 - --target /path/to/repo --profile context

# Team (default) — full lifecycle + CI/CD
curl -sSL https://github.com/rafex/SpecNative-Development/releases/latest/download/install.py \
  | python3 - --target /path/to/repo --profile team

# Repair broken MCP (no branch, no worktree check)
python3 install.py --reinstall --target /path/to/repo