Skip to content

tool-ecosystem.md

Latest commit

 

History

History
172 lines (139 loc) · 9.32 KB

tool-ecosystem.md

File metadata and controls

172 lines (139 loc) · 9.32 KB
Raw

Tool Ecosystem

Methodology vs. Tooling

Important

The methodology described in this framework stands on its own. A team can follow the legacy phased approach or the greenfield initialization recipe manually without any of the tools listed below. The tools accelerate adoption but are not prerequisites.

The agentic-ready approach has two distinct layers:

graph TB
    subgraph "Methodology (tool-agnostic)"
        subgraph "Part I: Readiness Foundation (Required)"
            M1["Phase 1: Bootstrap"]
            M2["Phase 2: Source-Level Docs"]
            M3["Phase 3: Agent-Oriented Docs"]
            M4["Phase 4: Contracts & Baselines"]
        end
        subgraph "Part II: Post-Readiness Roadmap (Agent-Driven)"
            M5["Phase 5: Refactoring (Optional)"]
            M6["Phase 6: Human Docs"]
            M7["Phase 7: Spec-Driven Dev"]
        end
    end

    subgraph "Tooling (accelerators)"
        T1["codebase-memory-mcp"]
        T2["agentic-tdd"]
        T3["agentic-docstrings"]
        T4["agentic-agentDocs"]
        T5["agentic-contracts"]
        T6["agentic-characterize"]
        T7["agentic-repoDocs"]
        T8["audit engine"]
        T9["audit and implement recipes"]
    end

    T8 -.-> M1
    T9 -.-> M1
    T1 -.-> M1
    T1 -.-> M2
    T1 -.-> M3
    T1 -.-> M4
    T1 -.-> M5
    T1 -.-> M6
    T1 -.-> M7
    T2 -.-> M5
    T2 -.-> M7
    T3 -.-> M2
    T4 -.-> M3
    T5 -.-> M4
    T6 -.-> M4
    T7 -.-> M6
Loading

A well-prepared codebase should give exceptional results with any coding agent — Claude Code, Cursor, OpenCode, Goose — and of course with agentic-tdd too.

Tool Maturity

Tool Status Phase Description
codebase-memory-mcp ✅ Available 1–7 Core intelligence layer. Indexes symbols, relationships, dependencies, tests, contracts. Queried by all phases.
agentic-tdd ✅ Available 5 Supports controlled, test-driven feature development and refactoring with AI agents.
audit engine (audit/engine/) ✅ Available 1 A read-only, standard-library Python scanner. It checks an existing repository against the Phase 1 readiness checks, with no LLM and no network, and writes a JSON and Markdown report. Run it from a clone of this repository; it is not yet released as a package.
audit recipe (audit/) ✅ Available 1 LLM-driven recipes for existing repositories, v0.2.0: the audit recipe runs today, end to end, as a SKILL.md bundle any coding agent with shell access can install. Builds on the audit engine and adds model judgment backed by cited evidence. The second recipe, which implements confirmed findings on a branch, is the next row.
implement recipe (implement/) ✅ Available 1 v0.2.0: all six stages (intake to close-out), the state tools (progress.py, check_drift.py, compare_reports.py) and the thirteen playbooks, bundled by dev/build_skills.py as the agentic-readiness-implement skill. Applied to two real repositories; see the worked example.
agentic-docstrings 📋 Planned 2 Will generate and maintain source-level documentation (docstrings, parameter descriptions, side effects).
agentic-agentDocs 📋 Planned 3 Will create structured, agent-oriented documentation and task-specific context packs.
agentic-contracts 💡 Aspirational 4 Will generate and validate API contracts, event schemas, and consumer-provider relationships.
agentic-characterize 💡 Aspirational 4 Will produce characterization tests and golden-master baselines for existing behavior.
agentic-repoDocs 💡 Aspirational 6 Will create human-facing repository documentation following the Diátaxis model. The manually created docs agentic-tdd can be found here. agentic-repoDocs will automate this process in the future.

Maturity Legend

Badge Meaning
✅ Available Existing, usable today
🚧 In development Being built now; parts exist, but it is not usable end to end yet
📋 Planned Actively planned for near-term development
💡 Aspirational Conceptual; development has not started

Tool Maturity Map

graph TB
    subgraph "✅ Available"
        T1["codebase-memory-mcp\n(Phase 1–7)"]
        T2["agentic-tdd\n(Phase 5)"]
        T8["audit engine\n(Phase 1)"]
        T9["audit and implement recipes\n(Phase 1, v0.2.0)"]
    end
    subgraph "📋 Planned"
        T3["agentic-docstrings\n(Phase 2)"]
        T4["agentic-agentDocs\n(Phase 3)"]
    end
    subgraph "💡 Aspirational"
        T5["agentic-contracts\n(Phase 4)"]
        T6["agentic-characterize\n(Phase 4)"]
        T7["agentic-repoDocs\n(Phase 6)"]
    end

    style T1 fill:#2d6a4f,stroke:#1b4332,color:#fff
    style T2 fill:#2d6a4f,stroke:#1b4332,color:#fff
    style T8 fill:#2d6a4f,stroke:#1b4332,color:#fff
    style T9 fill:#2d6a4f,stroke:#1b4332,color:#fff
    style T3 fill:#e9c46a,stroke:#f4a261,color:#000
    style T4 fill:#e9c46a,stroke:#f4a261,color:#000
    style T5 fill:#264653,stroke:#2a9d8f,color:#fff
    style T6 fill:#264653,stroke:#2a9d8f,color:#fff
    style T7 fill:#264653,stroke:#2a9d8f,color:#fff
Loading

Language Servers Beside the Code Index

A language server (LSP) and the code index answer different questions. Use both where the harness allows it.

Code index (codebase-memory-mcp) Language server
Gives the agent The whole-repository graph: callers, dependencies, tests, across languages Compiler-accurate definitions, references, types and renames for one language
After an edit A re-index refreshes the graph Type errors show at once
Needs from the repository An index registered for the checkout (IDX-01) The type-checker config, the import paths, and locked dependencies

A language server is an aid, never a gate. The repository's own type checker, run through its typecheck verb, stays the source of truth. No requirement asks for a language server to be installed.

How each harness reaches a language server (checked 2026-11-09 in each harness's own documentation):

Harness Route
Claude Code A code-intelligence plugin, for example pyright-lsp. The language-server binary must be on PATH
opencode Built in, off by default: "lsp": true in opencode.json. The server, for example pyright, must be installed
Cursor, VS Code The editor runs language servers for its extensions. Their docs do not say what the agent receives
Gemini CLI, Codex CLI, Antigravity No built-in route documented. Serena, an MCP server on top of language servers, fills the gap

Reference Implementation — agentic-tdd

agentic-tdd is the live worked example of Phases 1–4, including the Phase 1 command surface and the documentation contract. Copy its conventions instead of inventing local variants:

Practice Where to look
Agent governance — DI boundaries, commit and release lifecycle, documentation rules AGENTS.md
Canonical documentation rules — invariants, Diátaxis tracks, ADR lifecycle, doc-maintenance trigger docs/STYLE_GUIDE.md
Standardized command surface as package scripts — format, format:check, lint, typecheck, test, check, security package.json → scripts
CI invoking the same script names a developer runs locally .github/workflows/ci.yml, .github/workflows/security.yml
A real change set that updated docs alongside the code (npm run check gate, typecheck verb, STYLE_GUIDE compliance) docs/architecture/contributor-deep-dive/08-developer-guide.md § Verification Workflow

Repository: https://github.com/Nistapp/agentic-tdd. Some of the conventions above are on the branch under active development rather than the default branch — read the branch before copying, and treat this repository as the source of truth over any restatement here.

Shared Conventions

All tools will be published as independent open-source packages, each focused on a single responsibility. Node and TypeScript tools will be npm packages. Python tools, such as the audit engine, use only the standard library and run from a checkout or from a single-file .pyz, so they need no install step. The audit recipe already ships this way: dev/build_skills.py builds a self-contained agent skill (SKILL.md bundle) together with the Python tools it calls, installable with no checkout of the source repository. The implementation recipe follows the same pattern as a second bundle, installed beside the audit one. All of them share, or will share, common conventions for:

  • Configuration — consistent config file formats and defaults.
  • Reporting — structured output with provenance metadata.
  • Verification — each tool validates its own output before committing.
  • Integration — the tools that read code query and update codebase-memory-mcp. The audit engine reads the repository itself and only checks that an index exists.

← Home · Legacy Phased Approach · Risks and Mitigations