Blueprint Core

Blueprint Core is a local-first CLI that turns product evidence and guided answers into an AI-generated, traceable implementation blueprint.

It is for developers, QA engineers, and technical leads who need approved architecture, complete specifications, detailed tests, sprint tasks, and small copyable implementation prompts instead of unconstrained “vibe coding.” It does not implement application code itself.

The legacy init/retrofit engine remains available for compatibility. The ultimate workflow begins with setup, continues with generate, and requires review/approval before ClickUp synchronization.

What it does

Blueprint Core validates canonical source documents, connects to OpenAI, Anthropic, an OpenCode custom endpoint, or another OpenAI-compatible provider, applies bundled engineering standards, and generates:

• a versioned local blueprint store and knowledge lockfile;
• an AGENTS.md operating contract;
• a copied, pinned project knowledge pack;
• approved requirements, final architecture and decisions, complete specifications, detailed QA tests, and a spec tracker;
• dependency-ordered sprint tasks with token-efficient prompts, operational skills, evidence requirements, and ClickUp export;
• an implementation-readiness coverage manifest proving every feature section reaches requirements, specs, tasks, and tests;
• a typed trace graph connecting the blueprint, profile, decisions, knowledge, gates, skills, tasks, and test scenarios;
• fingerprints used to report later drift.

It does not execute sprint tasks, edit application code, claim planned tests were executed, or synchronize ClickUp without an explicit approval and confirmation.

How it works

The ultimate workflow: setup → generate → review → approve

This is the primary, AI-driven workflow described throughout this README. Every decision point below is real, taken directly from src/workflow/generate.ts's own 7-phase pipeline — nothing here is aspirational.

flowchart TD
    P0["providers / templates / frontend-designs / backend-patterns (optional, before setup)"] --> S["setup: project, sources, provider + model, role-specific questions, ClickUp"]
    S --> G12["generate 1-2/7: load config, preflight required documents, connect to provider"]
    G12 -->|"missing required doc, or provider is none"| G12X["Refuse with an actionable message"]
    G12 --> G3["3/7 evidence analysis"]
    G3 --> G4["4/7 architecture review"]
    G4 --> CB{"Blocking unresolved item?"}
    CB -->|"interactive terminal"| CB1["Ask live, apply the answer to the source doc, re-review"] --> G4
    CB -->|"non-interactive"| CB2["Fail fast with an actionable message"]
    CB -->|"none"| G5["5/7 delivery generation: requirements, specs, tasks, sprints, tests"]
    G5 --> G6["6/7 validate traceability + bounded semantic-repair loop"]
    G6 --> RP{"feature-list / architecture is ai-recommend?"}
    RP -->|"interactive"| RP1["Section-by-section proposal review"]
    RP -->|"non-interactive"| RP2["Accept the AI's proposal as-is"]
    RP --> AT{"Automation requested, tech stack ai-recommend?"}
    AT -->|"yes"| AT1["Automation tech-stack review"]
    AT --> FD{"Architecture has a client/frontend obligation?"}
    FD -->|"yes"| FD1["Frontend design review"]
    FD --> BD{"Architecture has a backend-module obligation?"}
    BD -->|"yes"| BD1["Backend architecture-style review"]
    BD --> SK["Thread any chosen design(s) into matching task skills"]
    SK --> G7["7/7 write every file atomically; record workflow-result.json status"]
    G7 --> RV["review"]
    RV --> AP["approve --approver name"]
    AP --> RPT["report"]
    RPT --> SY["sync clickup"]
    G7 -.->|"revision-requested"| REVISE["revise"] -.-> G12
    G12 -.->|"any time, once required docs exist"| EST["estimate"]

A few things worth knowing about this diagram:

• Every review step (architecture clarification, feature-list/architecture proposal, automation tech-stack, frontend design, backend architecture style) only happens in a real interactive terminal (never with --json, never without a TTY) and is bounded to a small number of rounds — none of them can loop forever, and none of them ever hard-block a non-interactive/CI run.
• The automation, frontend-design, and backend-design reviews are each conditional on something the architecture itself actually contains (an automation request, a client obligation, a backend-module obligation) — a project's role (developer/qa/combined) doesn't decide whether they fire.
• revise doesn't restart the pipeline from scratch: it records feedback in .blueprint/workflow-result.json, which the next generate run reads and folds into its architecture-review and delivery-generation requests.
• Phase-level and repair-level caching (see Repair caching below) mean re-running generate with nothing actually changed reuses completed work instead of re-asking the AI.

For a clickable product and architecture tour, open the interactive walkthrough.

The legacy deterministic engine (init/retrofit)

A separate, non-AI scaffolding engine remains available for compatibility. It shares no code path with the ultimate workflow above.

flowchart TD
    U[User runs init or retrofit] --> D[Discover repository files and classify repository]
    D --> P[Load or infer a project profile]
    P --> K[Load and validate bundled knowledge base and registries]
    K --> S[Score and select applicable knowledge]
    S --> Q{Selection decisions?}
    Q -->|default| A[Resolve with first option]
    Q -->|--decisions prompt| H[Prompt through the prompter port]
    A --> G[Deterministic generation pipeline]
    H --> G
    G --> V[Build gates, artifacts, trace graph, and fingerprints]
    V --> R{Write enabled?}
    R -->|init / retrofit --write| W[Atomically write generated files, then state and history]
    R -->|dry run| X[Print proposed report only]
    W --> L[check / status / doctor]
    L --> M[modify profile or update knowledge pins]
    M --> G

Human control happens through explicit command choice, profile authoring, dry-run review, and optional terminal decision prompts. --decisions prompt records valid terminal choices as human resolutions and aborts safely when no valid interactive answer is available.

Requirements and installation

• Node.js 20 or newer
• npm (the repository lockfile uses npm lockfile version 3)
• An OpenAI, Anthropic, or custom-compatible API credential is required for AI generation; credentials are read from environment variables and never stored

Run without a global install:

npx @macky_aletse/blueprint-core --help

Or install it in a project:

npm install --save-dev @macky_aletse/blueprint-core
npx blueprint-core --version

The package is named @macky_aletse/blueprint-core; its executable is blueprint-core.

Quick start

blueprint-core help --role developer or blueprint-core help --role qa prints a live, always-current version of the walkthroughs below, grouped by when you'd actually run each command.

If you're a developer

1. blueprint-core providers — see what credential each AI provider needs and where to get it, before running setup.
2. blueprint-core setup — choose role developer (or combined), a provider, and whether docs/feature-list.md/docs/proposed-architecture.md already exist or should be AI-recommended.
3. If you don't have starting documents yet, blueprint-core templates feature-list and blueprint-core templates proposed-architecture copy a Development-focused starting shape into docs/ — they refuse to overwrite an existing file unless you pass --force.
4. Optional: blueprint-core frontend-designs and blueprint-core backend-patterns browse the standard design/architecture catalogs generate will offer you — a time-saver if you already want to see the options.
5. blueprint-core generate --dry-run then blueprint-core generate. In a real interactive terminal (not --json, not CI), a blocking architecture question or an AI-recommended feature-list/architecture proposal is reviewed live, right there — you answer, edit, or ask the AI to revise a section before anything is written; running non-interactively keeps the original fail-fast/one-shot behavior instead. When the architecture has a frontend and/or backend surface, generate also asks about your frontend design and backend architecture style, always giving you an explicit recommendation either way (see Frontend and backend design steps).
6. blueprint-core estimate — once docs/feature-list.md and docs/proposed-architecture.md (or docs/architecture/README.md after a generate) exist, get a per-requirement/task hours range plus a rolled-up total, with your own team size and risk assumptions folded in interactively.
7. blueprint-core review, then blueprint-core approve all --approver "<your name>".
8. blueprint-core report to confirm implementation-readiness, then blueprint-core sync clickup --dry-run / --confirm if you use ClickUp.

Working against an existing, unmanaged repository instead of a clean slate? Run blueprint-core retrofit . --write first — it now analyzes real repository content (not just filenames) and additionally writes docs/deployment-guide.md, docs/setup-guide.md, docs/architecture/assessment.md (a coherence assessment with stated reasoning, not just a label), a seeded docs/change-history/CHG-001.md, and docs/specs/retrofit-discovery.md — a discovered starting point for real specs, additive to the generic docs/specs/README.md.

If you're QA

1. blueprint-core providers — see what credential each AI provider needs and where to get it, before running setup.
2. blueprint-core setup — choose role qa (or combined). If this is an automation project, setup asks which platform(s) it targets (web, mobile, desktop, or API/backend) and whether docs/proposed-automation-architecture.md already exists or should be AI-recommended; either way you're also asked whether you have docs/test-plan.md and whether to generate detailed positive/negative test cases.
3. If you don't have starting documents yet, blueprint-core templates feature-list --qa and blueprint-core templates proposed-architecture --qa copy a QA-focused starting shape — the feature-list variant is framed around describing the app's current behavior (what already exists to test), not a wishlist of new work.
4. Optional: blueprint-core frontend-designs and blueprint-core backend-patterns browse the standard design/architecture catalogs generate will offer you, so you know what to expect for combined-role projects that build a UI or a backend.
5. blueprint-core generate --dry-run then blueprint-core generate. generate refuses to run with an actionable message if detailedTestCases or automationProject is enabled but its required QA document is neither present nor configured as AI-recommended — it never silently proceeds with an empty QA source. When an automation tech stack is AI-recommended, it's presented for your explicit approval or a requested alternative — distinct from, and before, the general workflow approval — and recorded as its own decision in docs/requirements/decisions.json. On a combined-role project with its own frontend/backend surface, generate separately asks about frontend design and backend architecture style too (see Frontend and backend design steps).
6. blueprint-core estimate — once docs/feature-list.md and docs/test-plan.md (or docs/testing/test-cases.json after a generate) exist, get a QA-scoped hours range as a baseline you can add buffer to. For combined role, estimate runs both developer and QA scopes separately, plus a combined total.
7. blueprint-core review, then blueprint-core approve all --approver "<your name>".
8. blueprint-core report to confirm QA coverage and implementation-readiness.

Testing an existing, unmanaged application? blueprint-core retrofit . --write produces the same deployment/setup/architecture-assessment documents described in the developer walkthrough above — useful context for understanding what's actually deployed before writing QA scope against it.

Create or enter the project repository. If inputs already exist, use these exact names:

docs/feature-list.md
docs/proposed-architecture.md

Run setup and generation:

npx @macky_aletse/blueprint-core setup
export OPENAI_API_KEY="..." # or the environment variable selected in setup
npx @macky_aletse/blueprint-core generate --dry-run
npx @macky_aletse/blueprint-core generate
npx @macky_aletse/blueprint-core review
npx @macky_aletse/blueprint-core approve all --approver "<your name>"
npx @macky_aletse/blueprint-core report

Generation now fails before writing product artifacts when a feature-list section is lost, a requirement lacks a spec/task/test, detailed QA lacks a positive and failure-path test, a task contains an unresolved tool choice, or its skills, knowledge paths, and validation commands are not executable. The evidence is written to docs/coverage/implementation-readiness.json after a successful generation. An older generated project without that manifest is reported as not ready and must be regenerated.

The detailed-output contract also requires onboarding-grade architecture and setup sections, implementation-ready specification sections, explicit sprint objectives and exit criteria, small independently executable tasks, complete architecture-decision context and consequences, and directly executable QA records containing module, scenario, data, pre/postconditions, priority, requirement/spec traceability, and applied QA knowledge references.

Generation prints progress for evidence analysis, architecture review, delivery generation, validation, and file planning/writes. Each AI request allows 300 seconds by default. Slow local or custom endpoints can override it, for example:

blueprint-core generate --dry-run --timeout-seconds 600

Streaming output is summarized as periodic received-character counters; large structured JSON is not dumped into the terminal. Responses are stored under .blueprint/generation-responses/<input-digest>/. Generation checkpoints in .blueprint/workflow-run.json are persisted even during --dry-run, so an identical retry reuses completed evidence, architecture, and delivery phases. Dry-run never writes the planned product documents, but it does write this operational cache to avoid repeated AI token cost.

Repair caching

Beyond the phase-level checkpoint above, every raw AI response for a phase (evidence, architecture, delivery) is saved under .blueprint/generation-responses/<input-digest>/<phase>.json, keyed by the same input digest (a hash of the workflow config, sources, and revision feedback). When a response fails schema validation after the AI's own repair retries, the raw invalid response is saved separately as <phase>-invalid.json (for example architecture-invalid.json or delivery-invalid.json) instead of being discarded.

The next generate run with an unchanged input digest first tries to recover that cached invalid response through Blueprint Core's own deterministic normalization — the same vocabulary/shape fixes applied to any AI output — before spending another AI request on it. If normalization succeeds, progress reports it explicitly (for example "Recovered the cached architecture response after compatible JSON normalization; no new AI request was needed.") and no new request is sent. This exists so a transient, deterministically-fixable validation failure never costs a second round of AI tokens just to try again. Nothing here is cached across a changed input digest — any real change to sources, config, or revision feedback invalidates it and a fresh request is made.

For ClickUp export-only, use docs/tasks/clickup-import.json. For configured direct synchronization:

blueprint-core sync clickup --dry-run
blueprint-core sync clickup --confirm

Always review the dry-run first. Direct sync never performs remote deletes.

Choose the right workflow

Use setup and generate for the AI product. Use init or retrofit only for the legacy deterministic profile engine.

# Full product questionnaire and provider connection test
blueprint-core setup

# AI analysis and generation
blueprint-core generate --dry-run
blueprint-core generate
blueprint-core review
blueprint-core approve all --approver "<your name>"
blueprint-core report

# Existing repository: inspect, review JSON, then explicitly adopt
blueprint-core retrofit . --json
blueprint-core retrofit . --write
blueprint-core check

Setup authenticates before model selection. It fetches the models available to the connected account and asks you to choose from that result. OpenCode custom endpoints use baseURL and the API-key reference from opencode.json, while fetching selectable model IDs from the endpoint. Setup stores the chosen model and environment-variable references in .blueprint/workflow-config.json; it never stores the secret. OpenCode {env:VARIABLE_NAME} API-key references are resolved from the environment. If connection or discovery fails, setup stops and keeps a mode-0600 .blueprint/setup-draft.json containing only non-secret progress; the next setup run asks whether to resume it or begin again.

Status meanings

generate writes .blueprint/workflow-result.json on every successful run. Its status field is exactly one of three values:

| Status | Meaning | | --- | --- | | review-required | The default after a fresh or materially changed generation. No approval currently covers this exact source/delivery combination; run review then approve before treating it as implementation-ready. | | approved | Either approve all was run against this exact combination, or a regeneration reproduced source and delivery content byte-identical to the last approved run, so the prior approval still covers it — no re-review was needed. | | revision-requested | revise <entity> --message <text> was run. The feedback is recorded for the next generate to apply; regenerate before approving. |

This is a different field from .blueprint/workflow-run.json's own status (running, failed, completed, or aborted via abort), which tracks the generation process itself — whether a run is mid-flight, failed at a specific phase, finished, or was aborted — not whether the resulting product has been reviewed. review reports the workflow-result status above, plus whether sources or generated delivery have changed since the last recorded approval.

Frontend and backend design steps

When the reviewed architecture has a frontend/client surface, generate asks "Do you have a frontend design in mind?" before finalizing anything. When it has a backend surface, it separately asks "Do you have a backend architecture style in mind?" Each of these is its own conversational step — a project can trigger either, both, or neither, depending on what its own architecture actually needs.

• If you say yes, describe it in free text; the AI analyzes your description against a small registry of established options (see frontend-designs/backend-patterns below) and tells you plainly whether to keep what you described or switch to a specific listed alternative, with its reasoning.
• If you say no, generate presents that same registry and still makes one specific, opinionated pick with reasoning — never a bare list for you to choose from unassisted, and never "it depends."
• Either way, you can approve the recommendation, ask for an alternative (a bounded number of rounds, after which only approve/reject remain), or reject it outright — the same review shape generate already uses for an AI-recommended automation tech stack.
• In a non-interactive run (--json, or no TTY), neither step ever blocks generation: the AI picks its own recommended default automatically, and that choice is still recorded — just without a named human approver.

How to check what was chosen

• The frontend design ends up in docs/architecture/frontend-design-system.md; the backend architecture style ends up in docs/architecture/backend-architecture-style.md. Each file states what was chosen, why, and (for a registry pick) its fonts/color tokens/scale or its operational-cost/testability/dependency trade-offs.
• Each choice is also recorded as its own named decision in docs/requirements/decisions.json — look for the entries with id ADR-FRONTEND-DESIGN and ADR-BACKEND-ARCHITECTURE-STYLE. Neither is folded into the general workflow approval; approving all via approve does not itself constitute approving these.
• To confirm a specific generated task actually picked up the design, open its prompt at docs/tasks/sprints/SPRINT-*/TASK-*.md and check the Load skills: line: a frontend-facing task (UI/client work) lists apply-frontend-design; a backend-facing task (controller/domain/persistence/API work) lists apply-backend-design — alongside the skills every task already loads, never replacing them. A task with neither kind of surface, or a project where the corresponding design was never recorded, never gets one of these listed.

Command reference

All directory positionals default to the current directory. --dir <value> is an equivalent explicit form. All commands support --help; report commands support --json where shown.

| Command | Purpose | Interactive | Modifies repository | Success/failure notes | | --- | --- | ---: | ---: | --- | | init [dir] [flags] | Generate a blueprint for a new, empty, or compatible unmanaged repository. | No in the shipped CLI | Yes, unless --dry-run | Refuses initialized or incompatible repositories. | | setup [flags] | Configure project, canonical sources, role/QA/automation platform, provider, history/specs, and ClickUp. | Yes | Writes workflow configuration | Tests provider connectivity; never stores secrets. | | providers [--json] | List every supported AI provider, its credential, where to get it, and what setup will ask. | No | No | Sourced from the same provider definitions setup uses; nothing to configure. | | templates <feature-list|proposed-architecture> [dir] [--qa] [--force] | Copy a starting template into docs/. | No | Yes | Refuses to overwrite an existing file unless --force. | | frontend-designs [--json] | List every standard frontend design system generate can recommend. | No | No | Sourced from the same registry the conversational design step uses; nothing to configure. | | backend-patterns [--json] | List every standard backend architecture pattern generate can recommend. | No | No | Sourced from the same registry the conversational design step uses; nothing to configure. | | generate [dir] [--dry-run] [--json] | Analyze evidence and generate the ultimate blueprint. | Only in a live terminal (never with --json) | Yes unless dry-run | Requires configured provider credential; output requires review. | | review [dir] | List generated artifacts and approval state. | No | No | Requires a generated workflow. | | revise <entity> --message <text> | Record human revision feedback for regeneration. | No | Workflow state | Feedback is supplied on the next generation run. | | approve <entity|all> --approver <name> [dir] | Approve reviewed output. | No | Workflow state | approve all unlocks readiness and ClickUp sync. | | abort [dir] | Abort the current ultimate-workflow run. | No | Workflow-run state | Preserves completed checkpoints; resume with generate --resume. | | estimate [dir] [--json] | Conversational hours/days effort estimate. | Only in a live terminal (never with --json) | No | Refuses to run until its role's required canonical documents exist. | | report [dir] [--json] | Evaluate ultimate-product readiness. | No | No | Fails on missing inputs, artifacts, QA coverage, or approval. | | sync clickup [dir] [--dry-run|--confirm] | Preview/export or idempotently create/update ClickUp tasks. | No | Mapping file and optional remote tasks | Never deletes remote tasks; apply requires approval and --confirm. | | retrofit [dir] [flags] | Profile an existing unmanaged repository and preview adoption. | No in the shipped CLI | Only with --write | Refuses empty and already initialized repositories. | | modify --profile <file> [flags] | Re-select and regenerate from a replacement profile. | No in the shipped CLI | Yes, unless --dry-run or no material change | Requires an initialized repository. | | update [dir] [--dry-run] [--json] | Re-select against the bundled KB while preserving profile and decisions. | No | Yes unless dry-run or no material change | Requires an initialized repository. | | check [dir] [--json] | Validate core payloads, trace closure, pins, and file fingerprints. | No | No | Returns exit 6 for validation, drift, or trace failure. | | status [dir] [--json] | Summarize lifecycle, profile, selection, gates, tasks, trace, and drift. | No | No | Requires an initialized repository. | | doctor [dir] [--json] | Check the configured KB, history JSONL, and trace. | No | No | Returns exit 1 when its aggregate report is unhealthy. | | analytics [dir] [action] [--json] | Control and inspect project-local telemetry records. | No | on/off write consent | Consent defaults to off. |

init

blueprint-core init [dir] [--profile <file>] [--name <value>]
  [--type <value>] [--exposure <value>] [--criticality <value>]
  [--auto-approve]
  [--decisions <auto|prompt>] [--dry-run] [--json]
  [--answers <file>] [--resume <session-id>] [--non-interactive]
  [--provider <id>] [--model <id>] [--api-key-ref <ref>] [--base-url <url>]

Without --profile, it infers limited hints from repository filenames and fills remaining fields with defaults. --type accepts web-application, api-service, mobile-application, backend-service, desktop-application, data-pipeline, cli, library, or infrastructure. Exposure is internal, private, or public; criticality is low, medium, high, or critical.

With --decisions prompt, each pending selection decision is presented in an interactive terminal. Invalid input or EOF aborts safely with exit 2; non-interactive automation should use --decisions auto.

--answers <file> (a YAML/JSON file of repo_shape/role/agent_target/mode answers) or --resume <session-id> (continuing a previously aborted interactive session) run a short guided interview before init itself proceeds — useful for CI or for resuming a session you stepped away from. --non-interactive fails instead of prompting if any answer is still missing.

setup

blueprint-core setup

Setup requires exact canonical names when existing documents are declared. A near-match such as docs/features-list.md produces a rename suggestion and is never renamed automatically. API keys are masked and never copied into the workflow configuration. Progress before provider connection is cached in .blueprint/setup-draft.json; after an error, the next setup asks whether to resume it or discard it and start again. Successful setup removes the draft.

This is the interview for the AI generation workflow (generate/review/approve/report) specifically — it always writes .blueprint/workflow-config.json. If you're bootstrapping the separate, non-AI blueprint-scaffolding pipeline instead, use init --answers/init --resume (see above), not setup.

If role is qa or combined and you answer yes to "Is this an automation project?", setup also asks which platform(s) it targets — web, mobile, desktop, or API/backend, any combination — before asking whether docs/proposed-automation-architecture.md already exists.

providers

blueprint-core providers
blueprint-core providers --json

Lists every provider setup can connect to (openai, anthropic, opencode, custom, none), each with its default credential environment variable, where to obtain that credential, provider-specific setup steps, and the exact questions setup will ask for it, in order — read directly from the same provider registry setup itself uses, so it can't describe a provider setup no longer actually offers.

templates

blueprint-core templates feature-list [dir] [--qa] [--force]
blueprint-core templates proposed-architecture [dir] [--qa] [--force]

Copies a committed starting template to docs/feature-list.md or docs/proposed-architecture.md. Every template opens with a note that section headings must be kept exactly as written — only the content beneath each heading should change; proposed-architecture templates use every heading generate itself expects. Without --qa you get a Development-focused shape; with --qa, a QA-focused shape (for feature-list, framed around describing the app's current behavior rather than new work). Refuses to overwrite an existing target file unless --force is passed.

frontend-designs

blueprint-core frontend-designs
blueprint-core frontend-designs --json

Lists every standard frontend design system generate's conversational design step can recommend — Material Design 3, Apple Human Interface Guidelines, Microsoft Fluent 2, IBM Carbon, Ant Design, Atlassian Design System, Salesforce Lightning Design System, and a Tailwind + Radix/shadcn-style utility approach — each with its font pairing, color-token approach, spacing/typography scale, and UI-structural conventions. Read directly from the same registry the conversational step uses, so it can't describe an option generate no longer actually offers. Browse it as a time-saver before ever running generate, or just let generate ask and recommend one for you.

backend-patterns

blueprint-core backend-patterns
blueprint-core backend-patterns --json

Lists every standard backend architecture pattern generate's conversational style step can recommend — Layered (N-tier), Clean/Onion Architecture, Hexagonal (Ports and Adapters), Modular Monolith, Microservices, Event-Driven, and CQRS — each with its real trade-offs: operational cost, testability, and how swappable its external dependencies are. Same single-registry sourcing as frontend-designs.

estimate

blueprint-core estimate [dir] [--json]

Refuses to run until its role's required documents exist, naming exactly what's missing: a developer estimate needs docs/feature-list.md plus docs/proposed-architecture.md (or docs/architecture/README.md once generate has run); a QA estimate needs docs/feature-list.md plus docs/test-plan.md (or docs/testing/test-cases.json once generate has run). In a live terminal it asks a few optional questions — team size, focused hours per person per day, known unknowns, and a risk-buffer percent (default 20%) — then produces a per-requirement/task hours range plus a rolled-up total, always a range with stated assumptions, never a single number. For combined role it estimates developer and QA scope separately and adds a combined total. --json skips the questions and uses the default assumptions.

retrofit

blueprint-core retrofit [dir] [--profile <file>] [profile overrides]
  [--auto-approve] [--decisions <auto|prompt>] [--write] [--json]

The default is read-only. It reports detected and inferred facts, unknown fields, seed assumptions, selections, and the exact paths it would create. Pass --write only after reviewing that output.

Beyond the legacy scaffold, --write also analyzes real repository content — package manifest dependencies, entry points, CI workflow steps, Dockerfile contents, existing docs — never just filenames, and writes five additional documents: docs/deployment-guide.md (how this specific project is actually built and deployed), docs/setup-guide.md (onboarding for a new contributor), docs/architecture/assessment.md (a narrative of the architecture actually in use, a coherence verdict with stated reasoning, and concrete risks actually found — never a fabricated claim; every inferred, not directly observed, claim is labeled with a confidence level), a seeded docs/change-history/CHG-001.md, and docs/specs/retrofit-discovery.md (a discovered starting point for real specs, additive to the generic docs/specs/README.md and never replacing it).

modify

blueprint-core modify --profile ./new-profile.yaml [--dir <dir>]
  [--auto-approve] [--decisions <auto|prompt>] [--dry-run] [--json]

The profile file is the complete replacement profile, not a partial patch. Blueprint Core compares it with stored state, previews knowledge and file impact, then rewrites the generated set when a material profile or pin change exists. A change record is appended to .blueprint/history.jsonl. User-owned regions in a generated AGENTS.md are preserved only when the profile enables AI assistance and region mode is active.

update

blueprint-core update [dir] [--dry-run] [--json]

This reloads the currently bundled knowledge base and re-runs selection using the stored profile and decisions. It does not change those inputs. Changed generated files and pins are written, followed by a history entry and state manifest.

check, status, and doctor

blueprint-core check [dir] [--json]
blueprint-core status [dir] [--json]
blueprint-core doctor [dir] [--json]

check is the publication-quality validation surface: it reports modified, missing, and orphaned files under managed roots and validates trace closure. status is a summary, not an enforcement gate. doctor also works outside initialized projects; in that case it reports that no trace exists.

analytics

blueprint-core analytics . status
blueprint-core analytics . on anonymous
blueprint-core analytics . on detailed
blueprint-core analytics . report --json
blueprint-core analytics . off

--level anonymous or --level detailed can be used instead of the third positional. The implementation stores the same content-free command-run fields for both enabled levels.

Generated repository structure

The number of copied knowledge and task files depends on the selected profile.

my-project/
├── .blueprint/
│   ├── workflow-config.json    # provider/token references, never secrets
│   ├── workflow-result.json    # review/approval and generation evidence
│   └── clickup-map.json        # only after direct synchronization
├── .agents/skills/
│   ├── analyze-sources/SKILL.md
│   ├── apply-knowledge/SKILL.md
│   ├── maintain-specs/SKILL.md
│   ├── maintain-change-history/SKILL.md
│   ├── implement-task/SKILL.md
│   ├── test-task/SKILL.md
│   ├── review-evidence/SKILL.md
│   └── sync-clickup/SKILL.md
├── docs/
│   ├── feature-list.md
│   ├── proposed-architecture.md
│   ├── project-setup-guide.md
│   ├── architecture/README.md
│   ├── requirements/
│   ├── specs/
│   ├── testing/test-cases.json
│   ├── tasks/clickup-import.json
│   ├── tasks/sprints/SPRINT-*/TASK-*.md
│   └── change-history/
└── ...legacy deterministic artifacts only when init/retrofit is used

Every sprint task contains a copyable prompt with source/spec references, operational skills, applicable standards, allowed scope, non-goals, dependencies, measurable acceptance criteria, validation, evidence, and intervention triggers. Planned tests are not represented as executed evidence.

Knowledge, generation, and traceability

The package bundles Markdown engineering guidance with strict frontmatter plus YAML registries. Selection is deterministic: project characteristics are matched, scored, conflict-checked, and classified as applicable, potentially applicable, or not applicable. Selected document versions and copy modes are pinned in .blueprint/lockfile.json, and selected content is copied into docs/knowledge/.

The trace graph in .blueprint/trace.json relates the blueprint and profile to decisions, selected knowledge, quality gates, skills, tasks, and test scenarios. It does not currently model application code, executed test evidence, standalone requirements, or full specification entities. check verifies link closure against entities reconstructed from the trace file; it does not validate every generated YAML file against the domain schemas.

AI behavior

The public setup and generation path supports OpenAI, Anthropic, OpenCode custom endpoints, and other OpenAI-compatible endpoints. Setup probes the authenticated connection, discovers models, and only then asks which model to use. Generation uses structured output and validates required documents, task identity/dependencies, acceptance criteria, validation commands, and unresolved blockers before writing.

Raw secrets are never written to configuration, logs, prompts, generated documents, or ClickUp payloads. Automated tests inject recorded providers; the packed release smoke uses a local recorded provider through the real HTTP adapter.

Product boundaries and release status

The ultimate workflow is registered in the public executable. The deterministic profile engine remains a compatibility surface and has separate integrity semantics.

Consequently:

• report evaluates generated-product readiness; check continues to prove legacy managed-file integrity and drift;
• approval means a human reviewed generated planning artifacts, not that application code is correct;
• ClickUp apply requires approved output plus a separate --confirm action;
• publication requires the exact packed artifact to pass the recorded-provider ultimate workflow.

Programmatic API

The package root exports the engine functions plus collision-safe namespaces for the later domain APIs:

import {
  runInit,
  runCheck,
  requirements,
  specs,
  tasks,
  testing,
  gates,
} from "@macky_aletse/blueprint-core";

const requirementStore = requirements.createRequirementStore();
const specStore = specs.createStore();
const taskStore = tasks.createStore();

Only the package root and ./package.json are public export paths. Deep imports into dist/ are unsupported.

Configuration and environment

The CLI looks for .blueprint-core.json in the invocation directory. BLUEPRINT_CORE_CONFIG selects another JSON file, and BLUEPRINT_CORE_LOG_LEVEL overrides the log level. A malformed or explicitly missing config fails before command execution.

The supported configuration fields are knowledgeBase.path, log.level, and defaults.dryRun. Unknown fields fail validation instead of being silently ignored.

Example:

{
  "knowledgeBase": { "path": "/absolute/path/to/a-compatible-knowledge-base" },
  "log": { "level": "warn" },
  "defaults": { "dryRun": true }
}

Omit the file to use the bundled knowledge base and normal write behavior. The configured knowledge path is used by init, retrofit, modify, update, and doctor.

Dry-run and write safety

• init --dry-run executes discovery, validation, selection, decisions, and generation without writing.
• modify --dry-run reports the replacement profile’s impact without writing.
• update --dry-run reports pin and byte diffs without writing.
• retrofit is read-only unless --write is present.
• Generated files are written atomically per file; .blueprint/state.json is written last.

Writes, stale owned-file removal, history, fingerprints, and final state share a rollback boundary. If a write fails, Blueprint Core restores the previous managed files. Files no longer present in the new owned manifest are removed; user files outside that manifest are never targeted.

Analytics and privacy

Analytics are off by default and entirely project-local. Enabling analytics writes command name, exit code, duration, tool version, timestamp, consent level, and a truncated SHA-256 project reference to .blueprint/analytics.jsonl. The code contains no network sender. Commands continue if capture fails.

.blueprint/ai-usage.jsonl is included in reporting, but the public CLI path does not currently write AI usage records because it does not invoke a live provider.

Exit codes

| Code | Meaning | | ---: | --- | | 0 | Success | | 1 | Unexpected/internal failure, or an unhealthy doctor report | | 2 | Invalid command, flag, or user input | | 3 | AI provider failure (reserved by the error model) | | 4 | Required project/file not found | | 5 | Validation failure | | 6 | Drift, invalid blueprint payload, or broken trace closure reported by check |

Running with no command prints help to stderr and exits 2. An unknown command or option also exits 2.

Troubleshooting

• “Already initialized” — use status, check, modify, or update; do not run init again.
• “retrofit targets an existing unmanaged repository” — use init for an empty directory and lifecycle commands for an initialized one.
• Exit 6 from check — inspect its modified/missing/orphan entries. The command never auto-fixes drift.
• Config file could not be parsed — .blueprint-core.json must be strict JSON, not YAML.

Development

npm ci
npm test
npm run lint
npm run typecheck
npm run build
node dist/cli/entry.js --help
npm pack --dry-run
npm run test:release
npm publish --access public --dry-run

npm publish automatically runs prepublishOnly: the full tests, lint, typecheck, build, and test:release. The release smoke creates the real tarball, installs it in a clean consumer, imports the public API, runs greenfield generation and integrity checking, then verifies retrofit preview/adoption without modifying user source. Build output is ESM under dist/; runtime dependencies are limited to js-yaml and Node built-ins.

The package uses the authenticated maintainer's personal npm scope, @macky_aletse:

npm whoami
npm publish --access public --dry-run
npm publish --access public
npm view @macky_aletse/blueprint-core version

License

MIT