GitHub - vynazevedo/first-plan: Give AI coding tools the context and checks your project demands. Reuse existing code, follow team conventions, and verify changes with evidence.

Better AI code starts with understanding your project.

Quick Start - Capabilities - How It Works - Commands - Stack Lenses - Philosophy - Configuration - Troubleshooting - License

first-plan gives AI coding tools project context, existing patterns, and explicit requirements—then helps you verify changes with tests and scoped formal checks.

first-plan organizes project evidence in .first-plan/ and generates instructions for Claude Code, Codex, Cursor, GitHub Copilot, Cline and Aider. Coverage depends on the commands run and available sources. Instructions guide AI tools but do not guarantee adherence to every convention.

_{Deep integration for Claude Code (skills, agents, hooks). Tool-agnostic file generation for everyone else. Same IR, universal consumption.}

Evidence-first workflow (v1.5.0)

Before changing code, find existing implementations, tests and references with locations and hashes:

fpe context --query "validate email" --budget 8000 --json
fpe impact                            # candidate API consumers in registered repos
fpe deployment status                 # unknown until observations are recorded
fpe mcp --root /absolute/project/path  # read-only MCP over stdio

generate now preserves existing instructions and updates only its managed block. init --llm marks generated claims as inferred/unverified, records prompt sources, and discovers nested manifests. A release tag is not deployment evidence. Context and impact matches are candidates requiring verification.

See the v1.5 workflow, migration notes and limitations, evaluation methodology, and release procedure.

Formal verification pilot (v1.6.0)

The v1.6.0 verification pilot checks three Rust engine properties with Kani: context budgets, contract gate decisions and text preservation within an explicit bounded domain. The pilot includes deliberate mutation controls and evidence reports. See scope and reproduction.

Verifiable project rules (v1.6.0)

Register requirements in .first-plan/rules.yaml, retrieve obligations through fpe context --path, and run checks with fpe verify run using an externally reviewed policy. Rule/test changes require policy review. Passing tests and formal verification have distinct results. See workflow, limits and tenant example. Available in v1.6.0.

Quick Start

For Claude Code users (deep integration)

Install via the plugin marketplace:

/plugin marketplace add vynazevedo/first-plan
/plugin install fp

Then in your project:

/fp:init          # generate the full .first-plan/ IR
/fp:quick         # or a 1-page glance in 5 seconds

For any other AI coding tool (Codex, Cursor, Copilot, Cline, Aider, etc)

Install the engine standalone via cargo or binary download from releases:

cargo install --git https://github.com/vynazevedo/first-plan --tag v1.6.0 --locked first-plan-engine

First generate and review the IR using fpe init --llm (next section), or use an existing .first-plan/. Then generate instruction files for your tool of choice:

fpe generate --tool codex      # AGENTS.md
fpe generate --tool cursor     # .cursorrules + .cursor/rules/
fpe generate --tool copilot    # .github/copilot-instructions.md
fpe generate --tool cline      # .clinerules
fpe generate --tool generic    # CONVENTIONS.md (universal)
fpe generate --tool all        # all of the above
fpe generate --list            # see all available adapters

Configure your AI tool to load the generated instructions. File discovery and adherence depend on the tool and its settings.

Generate IR without Claude Code (v1.1.0+): `init --llm`

The engine now includes an LLM-agnostic init that generates .first-plan/ layers by calling OpenAI, Anthropic, or any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM) directly, so you can adopt first-plan even in projects that never touch Claude Code:

# OpenAI
export OPENAI_API_KEY=sk-...
fpe init --llm openai

# Anthropic: set FIRST_PLAN_LLM_MODEL to a model available in your account
export ANTHROPIC_API_KEY=sk-ant-...
fpe init --llm anthropic --model "$FIRST_PLAN_LLM_MODEL"

# Ollama (local, no API key)
fpe init --llm ollama --model qwen2.5-coder:latest

# Any OpenAI-compatible server (LM Studio, vLLM, self-hosted)
fpe init --llm openai --base-url http://localhost:8000/v1

# Preview what will be generated (no LLM call, no writes)
fpe init --dry-run

# Generate only specific layers
fpe init --llm openai --layer mission/purpose --layer topology/stacks

# List all layers
fpe init --list-layers

Config via env vars: FIRST_PLAN_LLM_PROVIDER, FIRST_PLAN_LLM_MODEL, FIRST_PLAN_LLM_BASE_URL. In v1.5.0, this command generates eight curated documents. Frontmatter records provider, model, timestamp, revision and source hashes, with confidence: null, epistemic_status: inferred and verification: unverified. Review inferences before relying on them.

Cross-repo awareness (v1.2.0+): `multi`

Teams working across multiple related repos (backend + frontend + mobile + infra, or a monorepo with multiple projects) can register sibling repos and aggregate their IR into a cross-repo overview:

# Autodetect sibling repos in a parent directory and register them all
fpe multi scan --parent ../ --register-all

# Or register manually with tags
fpe multi register --name backend --path ../backend --tag rust --tag api
fpe multi register --name frontend --path ../frontend --tag typescript --tag ui

# List registered repos with status (path exists? IR present?)
fpe multi list

# Generate cross-repo overview aggregating each repo's mission + stacks
fpe multi aggregate
# writes .first-plan/multi/OVERVIEW.md

# Remove a repo from the registry
fpe multi remove --name frontend

Config persists in .first-plan/multi.yaml. The aggregated overview shows a repo table (path, tags, IR presence) plus per-repo excerpts of mission/purpose.md and topology/stacks.md, giving any AI tool cross-repo context in one file.

Contract diff and breaking-change detection (v1.3.0+): `contracts snapshot` / `contracts diff`

Detect API contract regressions before they ship. The engine snapshots your OpenAPI specs and diffs any two snapshots, classifying each change as breaking or non-breaking:

# Snapshot current OpenAPI state (writes .first-plan/12-contracts/snapshot.json by default)
fpe contracts snapshot

# Diff between two snapshots
fpe contracts diff --before snapshot-v1.json --after snapshot-v2.json

# Diff current state against a baseline (no need to snapshot the "after" side)
fpe contracts diff --before snapshot.json

# CI: fail on breaking changes or incomplete analysis
fpe contracts diff --before baseline.json --fail-on-breaking

# Cross-repo check: for every registered sibling repo, diff current state
# against its baseline snapshot, aggregate breaking-change count
fpe multi contracts-check --fail-on-breaking

v1.5.0 coverage: conservative OpenAPI endpoint, parameter, body, response and security comparisons, with local reference resolution. --fail-on-breaking also rejects incomplete analysis, legacy snapshots and unsupported formats. The cross-repository gate rejects missing baselines and skipped repositories. Rebuild legacy baselines at their original revision. Protobuf/GraphQL diffs and complete semantic compatibility remain future work.

See value in 5 seconds (Claude Code): `/fp:quick`

/fp:quick

In ~1-5 seconds, generates .first-plan/quick/00-glance.md with:

Stacks detected (Cargo.toml, go.mod, package.json, etc - root + 1 level deep)
Entry points (main.*, index.*, server.*)
Top symbols (heuristic sample, kind-aware)
Recent commits + hot files (90d) + active authors
Naming convention detected (snake_case vs camelCase vs kebab-case)
Test framework detected
Suggested build/test commands

That's the first impression - enough context for Claude to start helping immediately, without waiting.

Then go deep: `/fp:init`

/fp:init

Generates the base discovery IR: stack analysis, reuse index, spec-code reconciliation, co-change graph and provenance. Additional engine commands enrich quality, contracts, evolution and runtime sections. Duration and coverage depend on repository size, available tools and the model.

For local development

/plugin marketplace add /local/path/to/first-plan
/plugin install fp@first-plan

Core capabilities

From understanding a codebase to checking a change: choose the capability that fits your task.

Understand the project

Capability	What it helps you do	Start here
Project discovery	Map stacks, conventions and reusable code into `.first-plan/`.	`/fp:init` · `fpe init --llm`
Task context	Find candidate implementations, tests and applicable rules with source locations and hashes.	`fpe context`
Code search	Retrieve indexed symbols with BM25; add embeddings or AST extraction with optional builds.	`fpe search` · Stack support
Symbol navigation	Resolve definitions and references through installed language servers; reuse warm servers with the Unix daemon.	`fpe lsp`
Change history	Identify files that often change together, deprecations and release history.	`fpe cochange` · `fpe evolution` · `fpe runtime`
Specs and quality	Review specification/code gaps, CI configuration and available coverage reports.	Reconciliation · `fpe quality`

Review and verify changes

Capability	What it helps you do	Start here
Project rules	Declare requirements, owners and source/test associations; surface obligations in task context.	Rules guide
Verification and policy review	Compare rule/test changes against an external policy and collect distinct test or formal results.	`fpe verify`
Formal verification pilot	Check three engine properties with Kani, explicit bounds and deliberate defect controls.	Scope and evidence
API compatibility	Compare OpenAPI baselines and flag breaking changes or incomplete analysis.	`fpe contracts diff`
Cross-repository impact	Find candidate API consumers and check contracts across registered repositories.	`fpe impact` · `fpe multi`
Deployment evidence	Record environment observations and distinguish deployed state from release tags.	`fpe deployment`

Work with your tools

Capability	What it helps you do	Start here
AI tool instructions	Generate managed instructions for Codex, Cursor, Copilot, Cline and Aider while preserving team-written content.	`fpe generate`
Read-only MCP	Expose task context, candidate impact and deployment observations to MCP clients.	`fpe mcp`
Claude Code workflow	Use discovery, planning, approval and execution skills with persistent project state.	Plan-first workflow
Freshness tracking	Mark affected context stale through Claude Code hooks; stream filesystem events with the watcher.	Living layer · `fpe watch`
Local utilities	Hash files and compress supported tool output using the native Rust engine.	`fpe hash` · `fpe compress`

Build options: the default binary includes BM25 search. Add -ast for tree-sitter extraction or -ml for hybrid search with embeddings. See engine installation.

Evidence has a scope: search and impact results are candidates; passing tests are not formal proofs. Formal results apply to the declared properties and assumptions. See verification limits and evaluation methodology.

Native Engine (v0.3.0+)

Starting with v0.3.0, the plugin ships a native Rust binary (fpe) that performs the heavy lifting outside of Claude. Operations that took minutes via shell+tokens now run in seconds.

Performance

Local engine operations need no LLM calls; init --llm uses the configured provider. Latency and resource use depend on the project and environment. The three v1.5.0 synthetic regression scenarios do not establish productivity gains with real agents; see evaluations.

Engine installation

Auto (recommended): On the first invocation of /fp:cochange or /fp:refresh, the plugin offers an automatic download:

Native engine not detected. Download? (~5MB, 10-100x speedup)
A) Yes B) No C) Manual

Manual: Download from Releases the binary matching your OS/arch. Extract and place in ${CLAUDE_PLUGIN_ROOT}/engine/bin/fpe (or anywhere in your $PATH).

v1.6.0 platforms:

Linux x86_64 and aarch64 (musl)
macOS Intel and Apple Silicon
Windows x86_64
Linux x86_64 GNU with ML (-ml suffix)
Linux x86_64 musl with tree-sitter (-ast suffix)

Seven distribution archives are published alongside SHA256SUMS for download integrity checks. Sizes vary by build. Building requires Rust 1.96 or newer; prebuilt binaries do not require Rust.

From source:

git clone --branch v1.6.0 --depth 1 https://github.com/vynazevedo/first-plan
cd first-plan/engine
cargo install --locked --path crates/cli                            # default lean build
cargo install --locked --path crates/cli --features=ml              # ML-enabled (embeddings)
cargo install --locked --path crates/cli --features=tree-sitter     # AST-enabled (precision)
cargo install --locked --path crates/cli --features=ml,tree-sitter  # both

Graceful fallback

Some plugin skills offer instruction and shell fallbacks. The fpe commands, including context, MCP and contract gates, require the engine; fallback does not provide full feature parity.

Real-World Example

Output of /fp:init on a Bash dotfiles repo (~50 scripts):

Detected stacks: Bash (pure)
Reuse Index: 8 idiomatic patterns identified
Classified features: 21
  IMPLEMENTED: 17
  DRIFTED: 4   (alert!)
  PHANTOM: 1   (alarm!)
  IN_PROGRESS: 0
  SPEC_ONLY: 0

Average confidence: 0.94
Open questions: 8 (in 08-meta/questions.md)

Suggested next actions:
1. Review phantom feature: F03 (README claims "200+ aliases", actually: 54)
2. Technical drift: F07 (`air` installed twice in golang.sh)
3. Answer questions Q2-Q8 with /fp:ask

Reuse Index examples

$ /fp:reuse "I need to detect the Linux distro"

Returns:

distro_detection (confidence 0.99):
  idiom: |
    if [ -f /etc/os-release ]; then
      . /etc/os-release
      DISTRO_ID="${ID}"
    fi
  seen_in:
    - zsh.sh:14-23
    - neovim.sh:12-18
    - docker.sh:12-18
    - pentest.sh:13-17
  inconsistency: "neovim.sh uses 'unknown' as fallback instead of exit 1"

Spec-Code Reconciliation example

$ /fp:check "CSV export endpoint"

Returns:

Match found: F12 - "CSV Export Endpoint"
Status: IMPLEMENTED (confidence 0.91)

Evidence:
- internal/handler/export.go:45 (full handler)
- internal/handler/export_test.go (8 test cases)

Recommendation: Feature already exists. Do not duplicate.

Living Layer in action

After editing README.md in the project, the PostToolUse hook automatically marks:

.first-plan/cache/.stale:
README.md

.first-plan/08-meta/coverage.md (entry added):
- README.md (modified at 2026-05-04T22:02) - affects: 09-features

You don't need to do anything - the hook detected it. When you run /fp:refresh, only those sections get re-analyzed.

Documentation

Getting Started

Quick Start - Installation and first init
Commands - All available slash commands
.first-plan/ structure - What gets generated in the target project

Architecture

How It Works - Main components
Stack Lenses - How each stack is analyzed
Living Layer - Automatic invalidation hook
Spec-Code Reconciliation - Feature matrix

Best Practices

Philosophy - 7 inviolable rules
Plan-First Workflow - Discovery -> Plan -> Approval -> Execution -> Report
Confidence Scoring - When the plugin asks instead of guessing

Configuration & Development

Configuration - Settings and customization
Development - Build, contribute, add a new stack lens
Troubleshooting - Common issues

How It Works

Main components:

Stack Lens Engine - detects manifests (go.mod, package.json, composer.json, etc), infers role (API/worker/lib/CLI/UI/infra) and routes to the matching skills/lens-<stack>/SKILL.md
Discovery Subagent (discovery-analyst) - read-only, runs Phase 1 in isolation, returns structured findings
Pattern Archeologist (pattern-archeologist) - extracts conventions with confidence scoring + concrete code examples
Reconciliation Auditor (reconciliation-auditor) - cross-references intent (docs, JIRA, GitHub issues via MCP) with evidence in code
Git Intelligence - inline read-only git commands for activity heatmap, ownership, in-flight (branches+PRs)
Living Layer Hook - PostToolUse watches edits and marks affected sections stale (does not regenerate - the user decides when to refresh)
State Machine - persisted in .first-plan/07-state/STATE.md, survives across sessions

Commands

Essential commands

Command	Purpose
`/fp:init`	Full compilation - creates `.first-plan/`
`/fp:refresh [section]`	Incremental refresh
`/fp:status [--verbose]`	Current layer state

Plan-First workflow

Command	Purpose
`/fp:plan <feature>`	Generate plan (Phase 2), pause for approval
`/fp:execute [--dry-run]`	Execute approved plan (Phase 3), generate report

Query commands

Command	Purpose
`/fp:why <symbol\|path>`	"Why does X exist?"
`/fp:reuse <intent>`	"What should I reuse for X?"
`/fp:risk <path>`	Catalogued risks
`/fp:ask`	Open questions for the human
`/fp:features [filter]`	Spec-Code Reconciliation matrix
`/fp:check <feature>`	"Does this already exist?"
`/fp:in-flight [--all\|--mine]`	Active branches/PRs
`/fp:hot [--days N]`	Most active areas
`/fp:owner <path>`	Who owns this file
`/fp:cochange <path>`	(v0.2.0) Files that change together with this one
`/fp:provenance <id>`	(v0.2.0) Provenance chain of a finding
`/fp:rollback [--snapshot]`	(v0.2.0) Revert last execute

Generated Structure

.first-plan/
├── INDEX.md                       entry point - Claude reads first
├── 00-mission/                    inferred purpose + stakeholders
├── 01-topology/                   stacks + architecture + boundaries
│   ├── stacks.md
│   ├── architecture.md
│   ├── boundaries.md
│   ├── deployments.md
│   ├── activity.md                heatmap (git)
│   └── ownership.md               per path (git)
├── 02-conventions/                extracted conventions with real examples
│   ├── naming.md
│   ├── errors.md
│   ├── testing.md
│   ├── logging.md
│   ├── di.md
│   └── security.md
├── 03-reuse/                      Inverted Reuse Index
│   ├── INDEX.md
│   ├── components.md
│   ├── utils.md
│   ├── types.md
│   ├── hooks.md
│   └── search.json                machine-readable lookup
├── 04-domain/                     glossary + entities + critical flows
├── 05-risks/                      fragile + untested + magic + debt
├── 06-rationale/                  do + dont + why (inferred decisions)
├── 07-state/                      State machine + plans + reports
│   ├── STATE.md
│   ├── in-flight.md
│   ├── sessions/                  ephemeral (gitignored)
│   ├── plans/                     active plans (Phase 2)
│   └── reports/                   execution reports (Phase 5)
├── 08-meta/                       coverage + confidence + questions + cache
└── 09-features/                   Spec-Code Reconciliation matrix

The plugin also appends to the target project's .gitignore:

.first-plan/cache/
.first-plan/07-state/sessions/

Stack Lenses

Dedicated lenses (with skill lens-<stack>):

Stack	Lens	Detects
Go	`lens-go`	cmd/internal/pkg, error wrapping, context.Context, concurrency, code generation
TypeScript/Node	`lens-typescript`	Next.js, NestJS, Vite, Express, Astro, Remix, monorepos pnpm/turbo/nx
PHP	`lens-php`	Laravel, Symfony, Slim, Hyperf, PSR compliance
Python	`lens-python`	FastAPI, Django, Flask, Litestar, Celery, src/flat packaging
Rust	`lens-rust`	axum, actix-web, tokio, error handling with thiserror/anyhow
Terraform	`lens-terraform`	modules, state backend, environments, providers, naming/tagging
Mobile	`lens-mobile`	RN, Flutter, iOS Swift, Android Kotlin
Other	`lens-generic`	Heuristic fallback (Elixir, OCaml, Haskell, Zig, etc)

Symbol extraction (engine - v0.4.0+)

Beyond the lens skills, the native engine extracts symbols (functions, types, classes) for the Reuse Index and semantic search:

Language	Regex (default)	Tree-sitter (--features=tree-sitter)
Go	✓	✓
Rust	✓	✓
TypeScript / JavaScript	✓	✓
Python	✓	✓
Bash / Shell (v0.5.0)	✓	✓
PHP	✓	-
Ruby, Java, Kotlin, Swift, Elixir	-	-

Tree-sitter mode delivers +43% precision in real-world tests. Default regex mode keeps the binary at ~1MB.

Add support for a new stack

Create skills/lens-<stack>/SKILL.md following the common contract in skills/lens-engine/SKILL.md. No other change is required - the engine discovers it via filesystem.

Spec-Code Reconciliation

Continuous matrix between intent artifacts (docs, specs, JIRA, GitHub issues, README sections) and implementation (code, tests, PRs).

Possible statuses

Status	Meaning
`NOT_STARTED`	Intent exists but no related code
`SPEC_ONLY`	Documentation complete, zero implementation
`IN_PROGRESS`	Partial implementation, active branch, or visible TODOs
`IMPLEMENTED`	Code complete, with tests
`DRIFTED`	Code exists but diverged from spec
`ABANDONED`	Stale branch + partial implementation

Phantom Features

Features marked IMPLEMENTED in code but still showing as Open in the issue tracker - high chance of imminent duplicated work. Detected and surfaced in .first-plan/09-features/INDEX.md.

Sources consulted

Local documentation (docs/, specs/, requirements/, rfcs/, README sections)
JIRA (via MCP jira-mm if available)
GitHub Issues and PRs (via MCP github-work if available)
Git history (branches, commit messages)
Code comments (TODO: implement, PLANNED:, FIXME)

Living Layer

The PostToolUse hook watches edits via Edit/Write/MultiEdit and automatically marks affected .first-plan/ sections as stale. It does not regenerate - it only signals. The user decides when to run /fp:refresh.

Modified file -> affected sections mapping:

Modified file	Sections marked stale
Manifest (go.mod, package.json)	`01-topology/stacks`
`cmd/`, entry points	`01-topology/architecture`
Handlers / routers	`01-topology/boundaries`
Dockerfile, CI configs	`01-topology/deployments`
Source code (>= 5 files)	`01-topology/activity`, `02-conventions/*`
`pkg/`, `lib/`, `utils/`	`03-reuse/*`
Tests	`02-conventions/testing`, `05-risks/untested`
docs/, specs/	`09-features/*`

Plan-First Workflow

Mandatory protocol with explicit human gate:

Discovery -> Plan -> Approval -> Execution -> Report

Phase 1 - Discovery

/fp:init

Result: .first-plan/ populated. Read-only subagents run discovery in isolation and return structured findings, which are written into the target project.

Phase 2 - Plan

/fp:plan <feature description>

Result: .first-plan/07-state/plans/<slug>.md containing:

Duplication check (queries 09-features/)
Applicable reuse mapping (03-reuse/)
Files to create/modify with conceptual diff
Convention adherence (02-conventions/)
Risks and open questions
"Done" criteria + explicit out-of-scope

Pauses for human approval.

Phase 3 - Approval

State: awaiting_approval in STATE.md. Nothing executes. The user approves with /fp:execute or asks for adjustments.

Phase 4 - Execution

/fp:execute

Follows the plan precisely. Stops if any premise becomes invalid - does not improvise. Updates STATE every step.

Phase 5 - Report

Generated automatically at .first-plan/07-state/reports/<slug>.md with:

What was done
What was reused vs created from scratch (with justification)
Plan deviations (if any)
Remaining risks
Out-of-scope suggestions

Philosophy

7 Inviolable Rules

Reuse first - Before creating, check .first-plan/03-reuse/INDEX.md. Creating from scratch requires explicit justification
The project's truth lives in the project - Do not import external best practices. If the project does it ugly but consistent, follow the ugly
No new dependencies - Use only what already exists in manifests. Adding a library requires separate approval
Consistency > elegance - Refactoring is out of scope unless requested. Suggestions go in the report's "out of scope" section
Creating from scratch is the exception - Allowed only when there is no precedent. Always justify
Faithful representation - Comments, docs, commits - all faithful to the project's writing style
Strong typing - Respect the project's type strictness. No any/interface{} if the project is strict

Confidence Scoring

The plugin protocol uses heuristic scores of 0.0-1.0, with a default threshold of 0.7. These are not calibrated probabilities. Standalone fpe init --llm records confidence: null; the table below does not apply to it.

Range	Meaning
`>= 0.9`	high confidence, multiple converging signals
`0.7-0.9`	good confidence, clear signal
`0.5-0.7`	medium confidence, circumstantial evidence
`< 0.5`	low confidence, becomes a question in `08-meta/questions.md`

The protocol directs the plugin to consult you via /fp:ask when confidence is low. AI output still requires review.

System Requirements

Standalone engine: a binary compatible with your system; Rust 1.96+ only when building from source.
Claude Code: required only for plugin skills, agents and hooks; use a version with plugin support
Git: for Git Intelligence (optional - if absent, related sections stay empty with a note)
bash: hooks use bash (Linux/macOS/WSL2)
Optional MCPs (improve coverage):
- jira-mm - reconciliation against JIRA issues
- github-work - reconciliation against GitHub issues/PRs

Discovery reads source without requiring the analyzed stacks' runtimes. Explicit fpe verify run executes reviewed project checks and requires their configured runtimes.

Configuration

The plugin requires no initial configuration - conventions are discovered during init. Optional customizations:

Confidence threshold

Edit the frontmatter of .first-plan/08-meta/confidence.md:

---
threshold: 0.7    # tune to 0.6 (more permissive) or 0.8 (stricter)
---

Exclude paths from the hook

To prevent changes to specific paths from triggering invalidation, edit hooks/invalidate-cache.sh or add a rule to the project's .gitignore.

Cache TTL

Git intelligence is cached for 24h by default in 08-meta/cache.json. To force a refresh:

/fp:refresh --all

Development

Plugin structure

first-plan/
├── .claude-plugin/plugin.json       manifest
├── commands/                        14 slash commands
├── skills/                          20 skills (1 protocol + 1 lens-engine + 8 lenses + 10 advanced)
├── agents/                          4 subagents (discovery, reconciliation, pattern, verification)
├── hooks/                           hooks.json + invalidate-cache.sh
├── templates/                       41 templates copied to .first-plan/ on init
├── meta-templates/                  internal plugin templates (plan, report, feature)
├── engine/                          Rust workspace (core lib + cli binary)
└── README.md

Add a new stack lens

Create skills/lens-<stack>/SKILL.md following the common contract in skills/lens-engine/SKILL.md
Add an entry in the detection table at skills/lens-engine/SKILL.md
No other changes required

Test locally

/plugin marketplace add /local/path/to/first-plan
/plugin install fp@first-plan
cd /some/project
/fp:init

To iterate, edit plugin files and run /plugin reload (or restart Claude Code).

Build the engine

cd engine
cargo build --release                           # default lean build
cargo build --release --features=ml             # ML build (with embeddings)
cargo test --workspace
cargo clippy --all-targets --workspace -- -D warnings
cargo fmt --all -- --check

Troubleshooting

`.first-plan/` not created after `/fp:init`

Check that the current directory is a valid project (has a manifest)
Check that the plugin is installed: /plugin list
Look at the subagent log in the init output for discovery errors

Hook does not invalidate sections after edits

Check permissions: chmod +x hooks/invalidate-cache.sh
Check log: tail -f ~/.first-plan-hook.log
Check that .first-plan/ exists in the project directory

Discovery very slow on a large monorepo

Discovery applies automatic sampling for projects > 1000 files
Use /fp:refresh <section> to refresh a single section
Increase time_budget_minutes in init if needed

False positives in DRIFTED

Edit .first-plan/09-features/<slug>.md manually to fix the status
The plugin respects manual edits until the next refresh of that feature

Low average confidence

Indicates a project with inconsistent or transitioning patterns
Check 08-meta/questions.md - answer the questions and refresh
Consider documenting conventions in CLAUDE.md for future discoveries

Contributing

Contributions welcome. Areas of impact:

New stack lenses - Elixir, OCaml, Haskell, Scala, Clojure, Zig
Subagent improvements - especially reconciliation-auditor
Performance optimizations for monorepos
More MCP integrations (Linear, Asana, Notion)
Roadmap features - tree-sitter AST, LSP integration, multi-repo, decision archeology

Workflow:

Fork the repository
Create a feature branch
Implement following the plugin's own conventions (see skills/protocol/SKILL.md)
Update documentation
Submit a Pull Request

Roadmap

Shipped

v0.1.0 - Initial release

Complete Discovery Layer (00-09)
Spec-Code Reconciliation with phantom features detection
Living Layer via PostToolUse hook
14 slash commands, 8 stack lenses, 3 read-only subagents

v0.2.0 - Cognitive Compiler Phase A+B

Provenance & Freshness Tracking - source/SHA/TTL/decay schema
Co-change Graph - change dependency from git history
Verification Loop - lint/typecheck/tests post-execute
Rollback / Time Travel - pre-execute snapshots

v0.3.0 - Native Rust Engine

fpe binary in a Rust workspace
cochange and hash subcommands (10-100x speedup)
Cross-platform pre-built binaries (linux x86_64+arm64, windows)
GitHub Actions CI/CD (lint, test, release)

v0.4.0 - BM25 Semantic Search

Engine index + search subcommands
Identifier-aware tokenization (snake_case + camelCase + UPPER_CASE)
BM25 ranking over symbols extracted from Go/Rust/TS/Python/PHP
semantic-reuse skill with graceful fallback
<10ms latency, zero Claude tokens

v0.4.1 - ML Embeddings

Opt-in --features=ml feature flag
core::embeddings with FastEmbedProvider (BGE-small, ONNX)
Hybrid search combining BM25 + cosine similarity
CLI --mode bm25|embed|hybrid + --alpha tuning
Auto-download of models in ~/.cache/first-plan/models/

v0.5.0 - Tree-sitter AST + Bash + Wikilinks

Bash extractor (regex) - dotfiles and shell scripts now indexable
- Supports function name() and POSIX name() forms
- Detects .bashrc, .zshrc, .bash_profile, .profile, .bash_aliases
Tree-sitter AST opt-in via --features=tree-sitter
- Exact parsing for Rust, Go, Python, TypeScript/JavaScript, Bash
- +43% extraction precision over regex (validated on real Rust project)
- Method auto-detection inside class/impl/struct
- Doc enrichment via line-based extractor fallback
Obsidian-compatible [[wikilinks]] in .first-plan/
- Inspired by OpenKB - turns the layer into a navigable graph
- INDEX.md template uses 30+ wikilinks for cross-references
- Skill protocol documents the convention

v0.5.1 - Watch mode

Engine watch subcommand - filesystem monitoring with debounced events
- notify-rs + notify-debouncer-mini
- Default debounce 5s (interactive); 300s recommended for production
- Language filtering (Go, Rust, TS, Python, PHP, Bash)
- JSON line stream on stdout (parseable by skill/wrapper)
- --exec '<cmd>' triggers external command per batch
- Inspired by OpenKB - goes beyond the PostToolUse hook (which only signals)

v0.5.2 - Visual polish

TTY auto-detection - pretty output when stdout is a terminal
- JSON mode preserved when piped or --json flag set
- Zero overhead in JSON mode
Colored output with crossterm: headers with box-drawing borders, status indicators, dim/bold contrast
Progress spinners during long ops in index (collect symbols, embeddings, write)
Score bars visual em search results
Strength badges coloring strong/moderate/weak in cochange
Pretty mode in all 5 subcommands: cochange, hash, index, search, watch
CLI deps: crossterm 0.28, indicatif 0.17, is-terminal 0.4

v0.5.3 - Native output compression

fpe compress --tool <tool> - reduces tokens consumed by Claude
- Tools: git-status, git-log, git-diff, git-branch, find, grep, rg, ls, cargo-check/test/metadata, npm-test, go-build/test
- Per-tool heuristics (group by dir, summarize by file, failures-only, etc)
- Graceful fallback: unknown tool passes through
Subagents prefer engine compress when available (discovery, pattern, reconciliation)
New skill compression-aware with usage docs
No external dependency needed (alternative to tools like rtk)
Measured: 1.5MB find -> 1.7KB (99.9%), 21KB grep -> 1.3KB (94%)

v0.6.0 - Polyglot LSP Integration

fpe lsp <op> - semantic symbol resolution via Language Server Protocol
- Operations: refs, def, symbols, hover, wsymbols, status, daemon
- 8 servers supported: rust-analyzer, gopls, pyright, typescript-language-server, intelephense, clangd, ruby-lsp, lua-language-server
- Auto-detect via manifests (Cargo.toml, go.mod, package.json, etc)
- Install commands suggested per OS - never auto-installs
Graceful fallback chain: LSP -> tree-sitter (when ast feature) -> grep+word-boundary
- Plugin works 100% without any LSP server installed
- used_fallback: true in JSON when LSP unavailable
JSON-RPC 2.0 client over stdio with Content-Length framing
New slash command /fp:lsp-status reports project LSP coverage
New skills lsp-aware (usage) and lsp-bootstrap (detection + install suggestions)
Subagents prefer LSP when available (discovery-analyst, pattern-archeologist, reconciliation-auditor)
Binary stays lean: 5.2 MB (+1 MB vs v0.5.3)

v0.6.1 - LSP daemon mode

fpe lsp daemon start --root <path> - warm-server pool over Unix socket
Eliminates cold start of 3-15s from second call onwards
All LSP ops auto-route through daemon when running (transparent to skills/subagents)
Lazy spawn: first request per server type pays cold start, rest are <100ms
Auto-shutdown after --idle-minutes (default 30) of inactivity
IPC: line-delimited JSON over Unix socket

v0.7.0 - Plugin rename to `/fp` + `/fp:quick`

Slash commands /first-plan:* renamed to /fp:* (breaking, migration in CHANGELOG)
New /fp:quick command produces 1-page glance in 1-5 seconds
Engine quick subcommand: stacks + entry points + top symbols + git activity + conventions + suggested commands
README hero pivot: "See value in 5 seconds, then go deep"

v0.7.1 - Windows build unblock + macOS test isolation

Daemon module gated #[cfg(unix)] with stub for Windows (was silently failing cross-platform builds since v0.6.1)
Daemon integration tests marked linux-only (macOS CI runners flaky)
All 5 cross-platform binaries publishing correctly again

v0.8.0 - Quality / Validation Layer

fpe quality - captures state of automated validation
CI workflows parsed: GitHub Actions, GitLab CI, CircleCI, Jenkins
Coverage reports parsed: lcov, cobertura, jacoco, jest, go coverprofile
Flaky test detection via git history mining (3 heuristics scored)
Output .first-plan/11-quality/ so AI knows what runs, what's tested, what's unstable

v0.8.1 - Frontmatter validator + first external contribution

YAML frontmatter validator in CI (motivated by @thejesh23 bug report #1)
commands/ask.md + skills/quality-aware/SKILL.md fixed by validator
New CONTRIBUTORS.md and CONTRIBUTING.md (EN + PT-BR)

v0.9.0 - Contracts Layer

fpe contracts - spec-code reconciliation
OpenAPI 3.x parser (YAML + JSON, 6 candidate locations)
Protobuf parser regex-based (no protoc dependency)
GraphQL SDL parser
Cross-referencer multi-language classifying each entity IMPLEMENTED / CANDIDATE / PHANTOM
Output .first-plan/12-contracts/ to support contract review and reuse

v0.10.0 - Evolution Layer

fpe evolution - deprecation and migration ledger
In-code deprecations detected cross-language (Rust #[deprecated], Java @Deprecated, JS/TS @deprecated, universal TODO(remove-after))
CHANGELOG parser (Keep-a-Changelog format)
Breaking commits detected via git history (5 kinds: ConventionalBreaking, BreakingChangeFooter, RefactorKeyword, MigrateKeyword, RewriteKeyword)
Replacement pairs inferred when removed + added files share similar names
Output .first-plan/13-evolution/ so AI stops suggesting patterns the team already replaced

v0.11.0 - Runtime Layer

fpe runtime - link between IR and release history
Release history via git tags with commit-count/author-count/CHANGELOG cross-reference
Unreleased commits post latest tag with breaking-change detection
File-to-release mapping (introduced_in + last_modified_in per source file)
Paralelized with rayon
Tracks tagged versus unreleased changes; deployment requires separate evidence

v1.0.0 - Framework Pivot

fpe generate --tool <name> - renders IR into tool-specific format
5 adapters: codex (AGENTS.md), cursor (.cursorrules + .cursor/rules/), copilot (.github/copilot-instructions.md), cline (.clinerules), generic (CONVENTIONS.md)
Trait-based adapter architecture for community-contributed templates
Tera template engine, versioned templates in adapters/ directory
Removes "I don't use Claude Code" objection - any AI coding tool consumes the same IR
Positioning change: "The context layer for Claude Code" → "The context layer for any AI coding tool"

v1.1.0 through v1.4.0 - Shipped

v1.1.0: provider-independent init (eight curated layers)
v1.2.0: repository registry and aggregated overview
v1.3.0: endpoint-level OpenAPI diff and cross-repository baseline checks
v1.3.1: fpe binary name with legacy alias
v1.4.0: terminal rendering and progress indicators

v1.6.0 - Verifiable project rules (current)

Explicit requirements, task-context obligations and externally reviewed verification policies
Distinct test/formal outcomes, evidence freshness checks and specification drift review
Kani pilot on production primitives and tenant-isolation regression example

v1.5.0 - Evidence and reliable change preparation

Managed instruction blocks preserve team rules; all section documents contribute context
Nested manifests, source samples, hashes and explicitly unverified LLM inferences
Task context with source/line/hash, character budget and stale-source checks
Conservative OpenAPI parameter/body/response checks, local reference resolution and strict incomplete-analysis gates
Candidate consumer references across registered repos and dated deployment observations
Read-only MCP stdio tools and reproducible evaluation scenarios
Release publication gated on tests, lint, versions and binary smoke checks; macOS binaries and SHA256SUMS

Planned - evidence-driven follow-up

Measured paired agent trials on real maintenance tasks; no effectiveness gain claimed yet
Semantic dependency resolution beyond lexical candidate consumers
Live deployment provider integrations beyond pipeline-supplied observations
Protobuf/GraphQL compatibility engines and broader OpenAPI compatibility semantics
Ranking and cache improvements driven by evaluation results

Long-term Vision

Complete Cognitive Infrastructure:

Bug Recurrence DB - "this bug appeared before in #234, fixed in abc123"
Decision Archeology - extracts why/because from commits/PRs/comments
Migration Tracker - "47% migrated from logrus → slog"
Doc-Code Sync auditor
Test-Code Drift detector
Investigation Mode - bug-hunt subagent
Onboarding Path Generator (per role)
Team Awareness (Slack/Linear sync)
Schema-Aware Operations (OpenAPI/GraphQL/Protobuf breaking change detection)
Multi-Tool AI Sync — extend adapters and measure adoption of generated instructions

License

MIT License - see LICENSE for full details.

Support

Issues: GitHub Issues
Repository: github.com/vynazevedo/first-plan
Author: Vinicius Azevedo (@vynazevedo)

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
.github/workflows		.github/workflows
adapters		adapters
agents		agents
assets		assets
commands		commands
docs		docs
engine		engine
examples/tenant-rules		examples/tenant-rules
hooks		hooks
meta-templates		meta-templates
skills		skills
templates		templates
tools		tools
verification		verification
.first-plan.toml.example		.first-plan.toml.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTORS.md		CONTRIBUTORS.md
LICENSE		LICENSE
README.md		README.md
logo.png		logo.png

Latest commit

History

Folders and files

Repository files navigation