SpecNative — how to work with this framework

MCP server — v0.4

tools/specnative_mcp.py exposes the repository as MCP resources, tools, and prompts so any MCP-compatible agent (Claude Desktop, Claude Code, OpenCode) can work spec-first without manually navigating the file tree. Requires: pip install mcp.

Quick setup — Claude Code

# Add via CLI
claude mcp add specnative \
  python3 .specnative/specnative_mcp.py \
  -- --repo /path/to/your/project

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

Resources

Tools

Prompts

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

Repository structure

repo/
├── AGENTS.md              # Agent operating contract — read first
├── README.md              # Navigation index
├── agents/
│   ├── README.md          # Context folder 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
│   ├── SPEC.md            # Active spec (or entry point to specs/)
│   ├── DECISIONS.md       # Persistent decisions and trade-offs
│   ├── ROADMAP.md         # Temporal direction, no implementation
│   ├── TRACEABILITY.md    # Links between artifacts
│   └── 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
└── .specnative/
    ├── SCHEMA.md           # Framework contract (not project content)
    └── CLI.md              # CLI reference

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. Do not ingest the whole repository.

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.

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 minimal or copy Template-Project-Agents-AI into the target repository. This creates all required folders and placeholder files.

2. Fill agents/PRODUCT.md

   Problem (what friction exists and for whom), Users (segments, needs, context), Goals (measurable outcomes), Non-goals (explicit exclusions), Differential value (why this solution deserves to exist).

3. Fill agents/ARCHITECTURE.md

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

4. Fill agents/STACK.md

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

5. Fill agents/CONVENTIONS.md

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

6. Fill agents/COMMANDS.md

   Actual project commands only: build, test, lint, run/start, migrations, and any project-specific operational commands. Never include framework CLI commands here.

7. Fill agents/ROADMAP.md

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

8. Create agents/SPEC.md (or agents/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.

9. Derive tasks/<initiative>/TASKS.md

   One task per implementable unit. Each task: ID, state, owner, dependencies, expected files, observable close criteria, validation command.

10. Record decisions in agents/DECISIONS.md

    Only persistent trade-offs that future initiatives must respect. Format: DEC-XXXX, date, state, context, decision, consequences, replaces.

11. Fill pipelines/CI.md and pipelines/CD.md

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

12. Update agents/TRACEABILITY.md when an initiative closes

    Link spec → tasks → decisions → main artifacts → validation evidence. Update at close, not during execution.

Agent workflow (from AGENTS.md)

1. Read the README.md of the current folder

   Entry point for navigation in any directory.

2. Check agents/ROADMAP.md

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

3. Read agents/PRODUCT.md and relevant technical context

   Load minimum context: ARCHITECTURE.md, STACK.md, CONVENTIONS.md as needed.

4. Read agents/DECISIONS.md

   Respect persistent trade-offs that condition the current design.

5. Review or create a SPEC.md

   Use agents/SPEC.md for single active specs; agents/specs/<initiative>/SPEC.md for larger projects.

6. Derive or read tasks in tasks/

   Follow workflows/PLANNING.md to turn spec into executable task list.

7. Implement following workflows/IMPLEMENTATION.md

   Verify CI gates from pipelines/CI.md before considering work complete.

8. Record persistent trade-offs in DECISIONS.md

   Only if the decision must survive beyond the current initiative.

9. Update TRACEABILITY.md at initiative close

   Link all related artifacts. Not during execution — only at close.

Required states

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.

Spec header (agents/SPEC.md or agents/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 (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 lives in the SpecNative Development repository, not in the adopting project. Invoke it pointing to the project root.

# 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

# Export traceability matrix
python3 specnative.py export-traceability --output exports/traceability.json

# Install into existing repository
python3 specnative.py install \
  --target /path/to/repo \
  --profile minimal \
  --include-examples \
  --branch specnative/install-v0.3.1

Standalone installer

install.py bootstraps SpecNative from a GitHub release with no dependencies beyond the Python standard library.

# Download and run
curl -sSL https://github.com/rafex/SpecNative-Development/releases/latest/download/install.py \
  | python3 - --target /path/to/repo

# Or download first, then run
python3 install.py --target /path/to/repo --profile minimal --include-examples