GitHub - vynazevedo/first-plan: Compiled context layer for any AI coding tool (Claude Code, Codex, Cursor, Copilot, Cline, Aider). 15 layers of structured IR + tool-specific generation.

Compiled context layer for Claude Code on complex projects.

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

Stop your AI coding tool from inventing new patterns. Make it follow your codebase's existing conventions, on cold session start, with absolute adherence.

first-plan compiles your project into a structured context layer (.first-plan/) with 15 layers of knowledge, then generates tool-specific instruction files so any AI coding tool (Claude Code, Codex, Cursor, GitHub Copilot, Cline, Aider) knows your stacks, conventions, idioms, hot files, contracts, deprecations, and runtime state before it writes a single line of code.

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

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 --path engine/crates/cli

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

Once IR is generated (see next section), any AI tool consumes the tool-specific file natively.

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
export ANTHROPIC_API_KEY=sk-ant-...
fpe init --llm anthropic --model claude-sonnet-5

# 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. 8 layers curated in v1.1.0, expanding in later versions. Each generated file gets YAML frontmatter with provider, model, and timestamp for provenance.

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-friendly: exit code 1 when any breaking change is detected
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

Breaking rules (v1.3.0, endpoint-level): removed endpoint = breaking, operation_id change = breaking, added endpoint / summary change / tags change = non-breaking. Parameter, request-body and response-schema diff, plus Protobuf and GraphQL support, ship in v1.3.1.

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

In ~3-8 minutes, generates the full 10-layer IR: stack lens analysis, reuse index, spec-code reconciliation, co-change graph, provenance tracking, living layer. This is what makes the difference between Claude inventing a new auth pattern vs Claude using your internal/auth/jwt.go as the template.

For local development

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

Core capabilities

	Context Compilation - structured multi-layer IR optimized for AI consumption
	Stack Lens Engine - pluggable detection and analysis per stack (Go, TS, PHP, Python, Rust, Terraform, Mobile)
	Inverted Reuse Index - "I need X, use Y at Z"
	Spec-Code Reconciliation - feature x status x evidence matrix
	Git Intelligence - heatmap, ownership, in-flight branches/PRs
	Living Layer - PostToolUse hook automatically marks sections as stale on edits
	Plan-First Protocol - explicit human gate before execution
	Confidence-Graded Knowledge - threshold 0.7, low-confidence findings become open questions
	Cross-Session State - today's session knows what yesterday's did
	Stack-Agnostic - generic fallback for any language
	Provenance Tracking (v0.2.0) - every finding has source/SHA/TTL/decay - audit where it came from
	Co-change Graph (v0.2.0) - "when X changes, Y also changes" - prevents incomplete PRs
	Verification Loop (v0.2.0) - automatic lint/typecheck/tests post-execute + rollback safety net
	Rust Engine (v0.3.0) - native binary fpe. Co-change graph for 50k commits in <2s vs 5min via shell. Parallel hashing of 10k files. Zero Claude tokens for heavy lifting.
	BM25 Semantic Search (v0.4.0) - "I need email validation" finds `validateEmailRFC` even without an exact name match. Local SQLite index, <10ms per query, 6 supported languages.
	ML Embeddings (Hybrid) (v0.4.1) - opt-in build with BGE-small (ONNX). Hybrid search combines BM25 + cosine similarity for true semantic matches.
	Tree-sitter AST (v0.5.0) - opt-in build with exact parsing. +43% extraction precision over regex. Auto-detects methods inside class/impl/struct. 5 languages: Rust, Go, Python, TypeScript, Bash.
	Bash extractor (v0.5.0) - dotfiles and shell scripts now indexable. POSIX `name()` and `function name` forms. Detects `.bashrc`, `.zshrc`, etc.
	Obsidian Wikilinks (v0.5.0) - `[[section/file]]` syntax across .first-plan/. Open as Obsidian/Logseq vault for graph navigation.
	Watch mode (v0.5.1) - `fpe watch` monitors filesystem with debounced events. JSON line stream on stdout. Inspired by OpenKB (continuous compilation).
	Native Output Compression (v0.5.3) - `fpe compress --tool <git/find/grep/cargo/etc>`. 80-99% token savings on large outputs. No external dependency needed.
	Polyglot LSP Integration (v0.6.0) - `fpe lsp <refs\|def\|symbols\|hover\|wsymbols>`. Semantic symbol resolution via 8 language servers (rust-analyzer, gopls, pyright, ts-lsp, intelephense, clangd, ruby-lsp, lua-ls). Auto-detects stack via manifests, suggests install commands for missing servers. Graceful fallback to tree-sitter + grep.
	LSP Daemon Mode (v0.6.1) - `fpe lsp daemon start`. Warm-server pool over Unix socket eliminates 3-15s cold start. Subsequent calls return in <100ms. Auto-routing: all LSP ops transparently use daemon when running, fall back to direct spawn otherwise.
	Quality / Validation Layer (v0.8.0) - `fpe quality`. CI workflows parsed (GitHub Actions, GitLab CI, CircleCI, Jenkins), coverage reports parsed (lcov, cobertura, jacoco, jest, go cover), flaky tests detected via git history mining. Produces `.first-plan/11-quality/` so AI knows what runs, what's tested, what's unstable before suggesting changes.
	Contracts Layer (v0.9.0) - `fpe contracts`. OpenAPI 3.x, Protobuf, GraphQL SDL parsed and cross-referenced with code. Each endpoint, RPC or operation classified as IMPLEMENTED, CANDIDATE or PHANTOM. Produces `.first-plan/12-contracts/` so AI never suggests code that breaks a contract nor implements what already exists.
	Evolution Layer (v0.10.0) - `fpe evolution`. Deprecations detected in code (@deprecated, TODO(remove-after), #[deprecated]) and CHANGELOG (Keep-a-Changelog format). Breaking commits via git history mining (feat!, BREAKING CHANGE, migrate/refactor keywords). Replacement pairs auto-inferred. Produces `.first-plan/13-evolution/` so AI stops suggesting patterns the team already deprecated.
	Runtime Layer (v0.11.0) - `fpe runtime`. Release history via git tags cross-referenced with CHANGELOG. Unreleased commits post latest tag with breaking-change detection. File-to-release mapping (paralelized via rayon, 11x speedup). Produces `.first-plan/14-runtime/` so AI answers "is this bug in production?" and "does this fix need a new release?".
	Multi-Tool Generate (v1.0.0) - `fpe generate --tool <name>`. Renders the same IR into 5 tool-specific formats: AGENTS.md (Codex), .cursorrules + .cursor/rules/*.mdc (Cursor), .github/copilot-instructions.md (GitHub Copilot), .clinerules (Cline), CONVENTIONS.md (Aider/generic). Framework pivot: any AI coding tool consumes the same compiled context.

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

Operation	Shell + Claude	Native engine
Co-change graph (50k commits)	~5 min	<2 s
Hash 10k files (xxh3)	~30 s	<500 ms
Claude token cost	~30k	~0

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).

Supported platforms (v0.5.0):

Default lean build (~1MB):

Linux x86_64 (musl, fully static)
Linux aarch64 (musl, fully static)
Windows x86_64

Opt-in builds:

Linux x86_64 GNU with ML build (-ml suffix, ~50MB, embeddings via fastembed)
Linux x86_64 musl with tree-sitter (-ast suffix, ~10MB, AST-precise extraction)

macOS (x86_64 + aarch64) coming back in v0.6.0. macOS users can build from source via cargo install --path engine/crates/cli for now.

From source:

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

Graceful fallback

If the engine is unavailable (no network, restricted environment, opt-out), all operations continue working via markdown fallback. The engine is an optimization, not a requirement.

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

Every finding has confidence: 0.0-1.0. Default threshold: 0.7.

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 plugin does not invent - it asks. When confidence is low, you are consulted via /fp:ask.

System Requirements

Claude Code: recent 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

Stack-agnostic - does not require specific runtimes for the analyzed stacks. The plugin reads code, it does not execute it.

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/ for AI to never break contracts nor duplicate implementations

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 production state
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 (11x speedup: 158s → 14s)
Answers "is this bug in production?" and "does this fix need a new release?"

v1.0.0 - Framework Pivot (current)

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"

Planned

v1.1.0 - LLM-agnostic init (Phase 2 of framework pivot)

fpe init --llm <provider> - discovery + patterns + reconciliation using any LLM
Providers: OpenAI, Anthropic, Ollama, Qwen (via OpenAI-compatible API)
Prompts embedded in binary, no dependency on Claude Code skills
Enables full first-plan usage without any AI coding tool - just the engine + API key
Enterprise scenarios: air-gapped with local Ollama, CI/CD pipelines, batch processing

v1.2.0 - Cross-Repo Awareness

~/.first-plan/repos.yaml config registry of sister repos
Cross-service call detection (OpenAPI/Protobuf/gRPC across repos)
/fp:blast-radius <symbol> command for microservices impact analysis
Combined with Quality + Contracts + Runtime = full downstream impact view

v1.0.0 - Framework pivot (multi-tool)

fpe generate --tool <claude|codex|cursor|copilot|generic> outputs tool-specific instruction files from IR
LLM-agnostic init: fpe init --llm <openai|anthropic|ollama|qwen> for users without Claude Code
Claude Code plugin remains the deep integration; other tools consume generated files
IR schema formalized as specification document

Long-term Vision (v1.5+)

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 (Cursor + Cody + Copilot consume .first-plan/)

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
Latest commit History 56 Commits
.claude-plugin		.claude-plugin
.github/workflows		.github/workflows
adapters		adapters
agents		agents
assets		assets
commands		commands
docs/i18n		docs/i18n
engine		engine
hooks		hooks
meta-templates		meta-templates
skills		skills
templates		templates
tools		tools
.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

Folders and files

Latest commit

History

Repository files navigation