vibe-blueprint

<p align="center"> <img src="docs/assets/vibe-blueprint-hero.png" width="100%" alt="Vibe Blueprint turns project facts into saved choices and reasons, then supports review only when requested." /> </p>

<h1 align="center">Vibe Blueprint</h1>

<p align="center"> <strong>Vibe Coding 开工蓝图</strong><br /> Build from a plan that remembers why. </p>

<p align="center"> Get a technical starting plan for your app shape, data and login, deployment, and project boundaries.<br /> Save the choices and reasons. Revisit them only when you ask. </p>

<p align="center"> <a href="#quick-start">Quick start</a> · <a href="#start--remember--revisit">How it works</a> · <a href="#technical-trust">Technical trust</a> · <a href="docs/security.md">Security</a> · <a href="docs/client-configs.md">Client setup</a> </p>

[!IMPORTANT] It plans the start. It does not build your app or watch your code.<br /> 它只规划怎么开工，不替你生成应用，也不会在后台盯着代码。

[!NOTE] This project is not yet published to npm. Install it from the public source repository for now.

Start with the app idea, not the tech vocabulary

You can ask in ordinary language:

I want to build a small expense reimbursement app. I do not understand tech stacks. Give me a practical starting plan, explain the important choices, and tell me what remains uncertain.

Vibe Blueprint can return a plan shaped like this:

Part of the blueprint	Example answer
App shape	Start with one web application instead of several services.
Data + login	Keep receipts and accounts in managed server-side storage with managed login.
Deployment	Use one managed deployment path for the first launch.
Boundaries	Include employee submissions and approvals; exclude payroll and direct money movement; confirm whether offline work is required.
Why	Fewer moving parts make the first version easier to build and maintain.
Drawback	The managed platform creates a vendor dependency.
Review trigger	Revisit the data approach if field staff must work through outages.

This is an illustration of the deliverable, not a universal recommendation for every expense app.

Start → Remember → Revisit

Start

Describe what you want to build and the realities that matter. The configured model extracts facts and proposes complete foundation routes. Code-based gates then reject hard-constraint failures, merge look-alike choices, remove dominated routes, check required minimum safeguards, and either select a route, ask one material question, offer at most two genuinely different business routes, escalate, or abstain.

The result covers the application shape, data and login, deployment, included and excluded capabilities, important assumptions, tradeoffs, and conditions that should trigger another review.

Remember

After you approve a proposal, Vibe Blueprint saves versioned, Git-friendly project state. Later coding sessions can retrieve the accepted choices and their reasons instead of reconstructing them from chat history.

The machine-readable source of truth remains:

.project-foundation/foundation.json

Readable and evidence-oriented artifacts include:

PROJECT-FOUNDATION.md
.project-foundation/session-brief.md
.project-foundation/evidence.json
.project-foundation/decisions.jsonl

Revisit

Review happens only when you or your coding agent requests it:

• a new requirement can trigger focused reassessment of affected capabilities;
• an on-demand Git scan can report combined payment, multi-organization, offline, and sensitive-data signals plus affected capabilities; and
• a registered evidence check can be previewed or run through the command allowlist.

A Git signal does not silently rewrite the saved blueprint, identify every affected decision with semantic certainty, repair code, block a commit, or run continuously in the background.

Quick start

Requirements

• Node.js 20 or newer
• npm
• Git for change scanning and commit-aware evidence
• your own key for an OpenAI Responses-compatible endpoint

No API key is bundled, shared, or read from Codex authentication files.

1. Install from source

git clone https://github.com/SinboBoop/vibe-blueprint.git
cd vibe-blueprint
npm ci
npm run build
npm link

This exposes:

• vibe-blueprint-mcp — the stdio MCP server; stdout is reserved for protocol messages.
• vibe-blueprint — secure credential management and local diagnostics.

2. Record your key locally

vibe-blueprint auth set
vibe-blueprint auth status

auth set accepts no key argument. It reads from an interactive terminal without echo and stores the credential in the platform user-config directory with restrictive permissions where supported. Never paste a key into chat or an MCP client configuration.

3. Register the MCP server

First resolve the executable's absolute path:

command -v vibe-blueprint-mcp

For Codex, replace the executable and project-root placeholders with absolute paths:

codex mcp add vibe_blueprint \
  --env FOUNDATION_ALLOWED_ROOTS=/absolute/path/to/projects \
  --env FOUNDATION_CODE_SHARING=none \
  -- /absolute/path/to/vibe-blueprint-mcp

Long model analyses may need the client timeout shown in the complete Codex, Claude Code, Cursor, and generic stdio configurations.

4. Install the thin Codex Skill

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
ln -s "/absolute/path/to/vibe-blueprint/skill/vibe-blueprint" \
  "${CODEX_HOME:-$HOME/.codex}/skills/vibe-blueprint"

The Skill decides when to invoke Vibe Blueprint and presents the result in plain language. The decision logic stays in the MCP server.

5. Check the real model connection

vibe-blueprint doctor /absolute/path/to/project --check-model

Then start a new client session and ask:

I want to build a small SaaS where agencies manage separate client workspaces and pay monthly. Create a Vibe Blueprint before coding.

For an existing project:

Field staff must now keep editing during outages. Revisit the saved blueprint before implementation.

For a normal bug, styling change, or isolated feature that does not cross a project-foundation boundary, use the ordinary coding workflow instead.

Technical trust

The model proposes; code-based gates check the proposal

Vibe Blueprint is not a prompt-only stack picker. Its configured model authors facts, candidate routes, scores, explanations, and safeguard declarations. Deterministic code validates that structured proposal against the documented Decision Integrity boundary: hard constraints, activity-risk rules, route equivalence and dominance, stable ordering, and minimum-invariant completeness.

Those checks reduce plausible-sounding choices that contradict the stated project realities. They do not prove a universally best stack, independently verify a vendor, inspect whether safeguards were implemented correctly, or certify production readiness.

Saved state does not depend on chat memory

An approved plan is written atomically as schema-versioned project state with readable summaries and an append-only decision record. Pending analysis_id values exist only in the running MCP process; restart the server before committing and the pending analysis is discarded, while committed project files remain durable.

Verification is constrained

Registered evidence commands run with separated arguments, shell: false, a controlled working directory, an allowlist, timeouts, output caps, redaction, and package-script hash binding. This is narrower than arbitrary command execution, but a passing check proves only what that registered check actually covers.

Repository checks

The repository includes automated tests, strict TypeScript checks, linting, protocol integration, installed-shape stdio checks, a checked-in known-regression inventory, and a repository secret scan. The inventory covers maintained failure families; it is not an expert-labelled representative benchmark, a general accuracy score, or evidence of superiority over another model.

Reproduce the checks locally:

npm ci
npm run lint
npm run typecheck
npm run build
npm test
npm run inventory:report
npm run test:protocol
npm run test:e2e
npm run scan:secrets
npm run check:skill
npm run check:brand
npm run check:package

Provider-backed verification is explicit, opt-in, and may consume quota:

npm run verify:live

Its sanitized record is scoped to that run; it is not an SLA or a production-readiness certificate.

The eight stable MCP tools

The foundation_* names below are stable protocol identifiers retained for compatibility; they are not a second public brand.

Tool	Responsibility
foundation_doctor	Check configuration, credential presence, allowed roots, model connectivity, saved state, and protection coverage.
foundation_analyze_project	Ask the internal model for facts and candidate routes, then apply activity-risk, invariant, and route checks.
foundation_answer_question	Apply the user's answer to the returned material-reality question and re-evaluate the recommendation.
foundation_commit	Atomically write a user-confirmed proposal to project-foundation artifacts without modifying application source.
foundation_get	Read saved state as JSON, Markdown, or a compact Session Brief.
foundation_assess_change	Compare a new requirement with committed state and reanalyse affected capabilities.
foundation_scan_changes	Inspect Git changes, dependencies, migrations, environment names, and structure for combined boundary signals.
foundation_verify	Preview or run one explicitly registered, allowlisted evidence check without a shell.

Security and privacy defaults

• Your key stays outside the repository. vibe-blueprint auth set uses a user-level credential file; CLI key arguments are rejected.
• No repository context by default. FOUNDATION_CODE_SHARING=none sends no caller-supplied summary, source, or Git diff.
• Explicit context ceilings. summary accepts only bounded, redacted structural text; only diff permits bounded, redacted added lines.
• Narrow filesystem access. Every project_root is canonicalized with realpath and checked against FOUNDATION_ALLOWED_ROOTS, including symbolic-link escapes.
• Untrusted repository text stays data. Comments, documentation, summaries, and diffs are isolated from instructions before model analysis.
• No arbitrary shell runner. Evidence commands use an allowlist, shell: false, timeouts, output caps, redaction, and package-script hash binding.
• Protocol-safe logging. stdio stdout carries MCP only; diagnostics go to stderr and redact headers, bearer tokens, and key-shaped strings.
• No silent model fallback. The configured model ID is preserved and reported when the provider rejects it.
• No response-storage request. Responses requests send store: false; the endpoint operator's infrastructure remains outside this project's control.

Read the complete security model and security reporting policy before sharing repository diffs or sensitive requirements.

Configuration

The FOUNDATION_* environment variables and .project-foundation/ state names remain stable protocol and persistence contracts.

Variable	Default	Purpose
FOUNDATION_LLM_API_KEY	none	Highest-priority credential; prefer vibe-blueprint auth set on a workstation.
FOUNDATION_LLM_BASE_URL	https://api.inferenvoy.com	Responses-compatible base URL.
FOUNDATION_LLM_RESPONSES_PATH	discovered	Explicit path override; otherwise /responses, then /v1/responses only after 404/405.
FOUNDATION_LLM_MODEL	gpt-5.6-sol	Exact model ID; never silently replaced.
FOUNDATION_LLM_REASONING_EFFORT	xhigh	Responses reasoning effort.
FOUNDATION_ALLOWED_ROOTS	server working directory	Platform-delimited roots under which project_root may resolve.
FOUNDATION_CODE_SHARING	none	Maximum repository context: none, summary, or diff.

Endpoint discovery caches only non-secret endpoint metadata in the user config directory. See .env.example for placeholders; never put a real credential in a tracked file.

Supported boundary

Vibe Blueprint is scoped to early Web apps, SaaS products, internal tools, and AI Web projects across five reviewed architecture patterns.

It is not:

• a complete application generator;
• a background repository monitor, automatic plan updater, commit blocker, or deployment blocker;
• a guarantee of the best technology stack;
• a universal architecture, vendor, medical, financial, legal, privacy, security, or compliance advisor;
• proof that declared safeguards exist in source code;
• a technology evidence catalog or exact-version freshness service;
• a production-readiness, security, or compliance certificate; or
• an expert-labelled general-quality benchmark.

Change scanning reports conservative signals and affected capabilities, not whole-program semantic proof or a replacement blueprint. Only separately configured hooks, CI checks, and protected branches can turn selected findings into technical blockers.

See the Decision Integrity release notes for the exact compatibility contract.

Compatibility note

Before the public rename, local checkouts used the pre-release executable aliases foundation-guard and foundation-guard-mcp and stored credentials under a foundation-guard user-config directory. This package temporarily keeps those executable aliases and safely reads that credential location when the new one is absent, so existing local users do not need to re-enter a key. New setup should use vibe-blueprint, vibe-blueprint-mcp, the vibe_blueprint client key, and the skill/vibe-blueprint path.

The eight foundation_* tools, FOUNDATION_* settings, .project-foundation/ directory, PROJECT-FOUNDATION.md, and schema version 1 intentionally remain stable.

Upgrade and removal

Upgrade a source checkout with git pull --ff-only, npm ci, npm run build, npm test, and npm link. Review the release notes before upgrading a shared project because the Decision Integrity contract adds abstain as a fifth successful interaction mode.

Before uninstalling the executable, remove the user credential and MCP registration:

vibe-blueprint auth delete
codex mcp remove vibe_blueprint
npm unlink --global vibe-blueprint-mcp

Uninstalling does not delete .project-foundation/ or PROJECT-FOUNDATION.md from projects; those are project records and must be reviewed separately.

Contributing and security

Issues and pull requests are welcome. Do not put keys, private source, raw diffs, exploit details, or unredacted logs in a public issue. Follow SECURITY.md to report vulnerabilities privately through GitHub.

License

MIT