Prompt Builder

Compile-time orchestration prompt generator for coding agents. Turn vague tasks — "yoxla bu səhifəni", "timer əlavə et", "review admin dashboard" — into paste-ready prompts with API-shaped contracts, code-grounded diagnosis, lean task rows, skill discovery, verification gates, and optional Agent-Native visual plans for human approval before code runs.

• A diagnosis-and-prescription plan compiler (text IR + optional visual IR)
• The contract layer agents execute against
• Token-budget aware (default 6000 tokens for the lean prompt)
• A bridge to BuilderIO/skills /visual-plan and /visual-recap

Dual output model: the orchestration prompt is always lean text (machine IR). Human/visual artifacts live in metadata or plans/<slug>/ — never stuffed into the 6000-token budget.

Progressive Disclosure

| Doc | Purpose | |-----|---------| | SKILL.md | Full workflow: Understand → Ground → Diagnose → Conclude | | QUICKREF.md | Flags, modes, validation scoring, script map | | REFERENCE.md | Architecture, templates, extension points | | ROADMAP.md | Source-backed roadmap | | references/anti-slop-guide.md | 45+ anti-slop patterns, scoring, writer→reviewer | | references/anthropic-skills-patterns.md | Official anthropics/skills invocation |

Install

npx @vaqif14/prompt-builder "design pricing card component"
npm install -g @vaqif14/prompt-builder

Critical: run from the target project repo root. cwd drives Grounded Targets, stack detection, and real pnpm test / ./gradlew test commands. Running inside the prompt-builder package when generating for another repo silently degrades grounding.

Optional — visual plan viewer (for plans/<slug>/ preview and hosted collaboration):

npx @agent-native/skills@latest add visual-plan visual-recap

Architecture: Text IR + Visual Presentation

Prompt Builder separates what the agent executes from what the human approves:

flowchart TB
  subgraph compile [Compile time — prompt-builder]
    A[Vague task] --> B[Mode + platform + stack]
    B --> C[Grounded Targets from cwd]
    C --> D[Lean prompt scaffold + RESOLVE slots]
    D --> E[Fill from code: PROBLEM ANALYSIS + TASK PLAN]
    E --> F{planFormat}
    F -->|lean| G[Text prompt only]
    F -->|human| H[Text prompt + *.plan.mdx]
    F -->|visual| I[Text prompt + plans/slug/]
  end

  subgraph review [Human review — optional]
    I --> J["/visual-plan or local serve"]
    J --> K[Approve / comment on MDX blocks]
  end

  subgraph execute [Agent execution]
    G --> L[Agent runs lean TASK PLAN rows]
    H --> L
    K --> L
  end

  subgraph recap [Post-execution — optional]
    L --> M["/visual-recap on branch diff"]
    M --> N[File-tree + annotated diffs + wireframes]
  end

| Layer | Format | Consumer | Lives in | |-------|--------|----------|----------| | Agent IR | Lean markdown prompt (T001 rows, contracts, failure gates) | Coding agent | Terminal, *.md, plans/<slug>/prompt.md | | Human plan | MDX tables + phases | You, PM, reviewer | *.plan.mdx | | Visual plan | Agent-Native MDX (RichText, QuestionForm, wireframes) | You via Plan viewer | plans/<slug>/plan.mdx | | Visual recap | Diff-derived MDX (file-tree, key-change tabs) | PR reviewer | Hosted plan or plans/<slug>/ with kind: recap |

Philosophy: plans are the new intermediate representation — like assembly before machine code. As execution reliability improves, investment in plan quality pays off disproportionately. Prompt Builder compiles the text IR; BuilderIO/skills renders the visual approval surface.

End-to-End Workflow

1. Generate — CLI emits scaffold (Solution: DRAFT, Plan: DRAFT).
2. Read code — resolve grounding slots and <RESOLVE> markers to real file:line.
3. Diagnose — fill PROBLEM ANALYSIS with root cause + specific fix (not "go find the bug").
4. Plan — fill lean T001/F001 rows with acceptance + verify commands.
5. Review (optional, --visual) — publish MDX plan; approve before any source edits.
6. Hand off — paste lean prompt into Claude Code/Cursor, or --save when both readiness axes are ready.
7. Recap (optional, --visual-recap) — after execution, /visual-recap on the work-unit diff.

Quick Examples

# Auto mode + platform
prompt-builder "review admin dashboard and confirm all working"
# → lean prompt; visual-plan + visual-recap skills recommended in MATCHED SKILLS

# Security audit
prompt-builder --mode security-review "audit auth flow"

# Plan formats — agent prompt ALWAYS stays lean
prompt-builder --plan-format human "add timer"
prompt-builder --plan-format human --save-draft task.md "add timer"
# → task.md + task.plan.mdx

prompt-builder --visual "redesign checkout screen"
# → writes plans/<slug>/ immediately + embeds VISUAL PLAN WORKFLOW section

prompt-builder --visual --visual-recap --visual-dir plans/checkout-v2 "api migration"
# → custom dir + Phase C recap instructions in workflow

prompt-builder --visual --save-auto --force "redesign admin dashboard"
# → ./<slug>.md + plans/<slug>/ (plan.mdx, prompt.md, canvas.mdx if UI)

# Session loop + discovery
prompt-builder --discover "review dashboard"
prompt-builder --profile web "design pricing card"
prompt-builder --json "fix bug"    # includes metadata.visualPlan, humanPlan, title, slug
prompt-builder --record-outcome sess_xxx success "CI green"

Visual Planning (Agent-Native)

Integrated with BuilderIO/skills — /visual-plan (approve before code) and /visual-recap (review after code).

When visual planning kicks in

| Signal | Behavior | |--------|----------| | --visual or --plan-format visual | Full workflow section + plans/<slug>/ artifacts | | design-review, UI surfaces, High complexity | visual-plan + visual-recap in MATCHED SKILLS (lean prompt) | | architecture-review, migration-plan, prd-to-tasks | Same skill recommendation | | Trivial one-liners (fix typo, rename var) | Skipped — agent should just edit |

Lean mode shows a CLI hint (💡 Visual plan recommended) without bloating the prompt. The full VISUAL PLAN WORKFLOW section (Phase A/B/C) is injected only when --visual is set.

plans/<slug>/ artifact manifest

plans/<slug>/
├── plan.mdx           # Agent-Native plan (RichText blocks, open questions)
├── prompt.md          # Full lean orchestration prompt (source of truth for agent)
├── canvas.mdx         # UI wireframe stub (when web/mobile/desktop detected)
└── .plan-state.json   # kind, stack, hasCanvas, includesRecapPhase

Preview locally (reads from your machine, not the hosted DB):

npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan --open

Or pass the filled prompt as planText to Plan MCP create-visual-plan after installing the skill.

Closed loop

prompt-builder --visual "feature X"
  → fill RESOLVE slots from code
  → /visual-plan (planText = prompt.md) → human approves
  → agent executes lean TASK PLAN rows only
  → /visual-recap on branch diff → PR-ready visual review

Rule: planning is read-only until sign-off. Scope shifts update the plan document, not just chat.

Intent Routing

| User says | Mode | |-----------|------| | review, audit, check, verify, QA, yoxla, təsdiq, all working | audit | | fix, bug, error, broken, xəta, səhv | bugfix | | refactor, rewrite, modernize, clean | refactor | | design review, visual, does this look good | design-review | | architecture, coupling, hexagonal | architecture-review | | security, CVE, auth audit | security-review | | slow, optimize, profile | performance-review | | release, deploy, ship | release-check | | prd, spec, break into tasks | prd-to-tasks | | add, implement, build, əlavə et | feature (default) |

Generated Prompt Structure

Default budget 6000 tokens. P0 sections survive compression; visual workflow is P2 and only present in --visual mode.

| # | Section | Role | |---|---------|------| | 1 | System Contract | Role, mission — governed by Prompt Contract | | 2 | Prompt Contract | Goal · Inputs · Output · Constraints · Failure · Anti-Slop §6 | | 3 | Workflow Pattern | Composable agent shape + rationale | | 4 | Quality Bar | dev-metrics 6-axis target | | 5 | Grounded Targets | Stack, commands, ranked files, invariants | | 6–7 | Exploration + Grounding | Search rules; slots → file:line | | 8 | Clarify-First Gate | A/B repo paths when target unclear | | 9 | Problem Analysis ⬅ | Root cause, hypothesis, fix direction | | 10 | Write Safety Gate | Plan approval + invariant fence | | 11–14 | Skills | Discovery, matched skills (+ visual-plan/recap when fit), task board, council | | 15 | Task Plan ⬅ | Lean T001/F001 rows or findings ledger | | 15b | Visual Plan Workflow | Phase A/B/C — only with --visual | | 16–18 | Execution | Tools, constraints, stack practices | | 19 | Verification Contract | source / command / screenshot / blocked-by | | 20 | Acceptance + Output Schema | Deliverable shape |

Readiness (two axes)

| Axis | ready when | |------|----------------| | solutionReadiness | PROBLEM ANALYSIS has real path:line, no <RESOLVE> | | planReadiness | TASK PLAN rows filled with file paths + acceptance | | readiness | both axes ready |

validation.score 100/100 with readiness=draft is normal — the scaffold is not hand-off ready until you fill it from code. --save refuses drafts; --save-draft exports intentionally.

Plan Formats: lean · human · visual

| Format | Agent prompt | Side artifact | Token budget | |--------|--------------|---------------|--------------| | lean (default) | Compact T001/F001 + contracts | Skill hints for visual-plan when fit | ≤ 6000 | | human | Same lean prompt | metadata.humanPlan → *.plan.mdx on save | Lean prompt only | | visual | Same + VISUAL PLAN WORKFLOW | plans/<slug>/ MDX folder + serve command | Lean prompt only |

prompt-builder --plan-format human --save-auto "add saved-search"
# → add-saved-search.md + add-saved-search.plan.mdx

prompt-builder --visual --force "redesign admin dashboard"
# → plans/redesign-admin-dashboard/  + CLI prints serve command

Token discipline: MDX/markdown tables are efficient in docs. HTML wireframes and interactive blocks belong in plans/ or /visual-plan — not in the orchestration prompt. The agent reads prompt.md; humans read plan.mdx.

Prompt Contract + Anti-Slop

Prompts are API contracts, not creative briefs:

Goal        → measurable success (acceptance criteria)
Inputs      → task, grounded targets, stack, skills invoked
Output      → exact schema (findings ledger / solution table / changelog)
Constraints → hard walls (scope, safety, invariants)
Failure     → breach = STOP (includes anti-slop + read-only edit violations)
§6 Anti-Slop → horoscope test, Tier 1 bans, structural tells, code/design slop
Gist exec    → artifact size rule (>20L/>1500c), SKILL.md pre-read, no faked tool output

Horoscope test: Could anyone have written this for anyone? → add file:line, metrics, author-specific opinions.

Full catalog: references/anti-slop-guide.md

Skill Ecosystems

Anthropic official (anthropics/skills)

Task-fit matches injected before generic discovery — frontend-design, webapp-testing, mcp-builder, document skills.

/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

Catalog: data/anthropic-skills-catalog.csv · Patterns: references/anthropic-skills-patterns.md

BuilderIO ecosystem (BuilderIO/skills)

Planning and review skills matched by mode + task signals:

| Skill | Role | |-------|------| | visual-plan | Rich MDX plan — wireframes, API/schema blocks, approval gate | | visual-recap | Post-execution diff recap — file-tree, annotated key changes | | read-the-damn-docs | Authoritative docs before package/framework changes | | quick-recap | Green/yellow/red status block (optional polish) |

Catalog: data/ecosystem-skills-catalog.csv · Install: npx @agent-native/skills@latest add visual-plan

Workflow Patterns

| Pattern | When | |---------|------| | single-pass | Low complexity, one surface | | prompt-chain | Sequential dependent steps | | routing | Mode/surface dispatch | | parallel-review | Independent review lanes | | orchestrator-workers | High complexity, multiple targets | | evaluator-optimizer | Quality loop with rubric | | autonomous-loop | Only when explicitly warranted |

Modes (14)

| Mode | Use for | |------|---------| | feature | Add, implement, build (default) | | audit | Review, check, verify, QA | | bugfix | Fix, reproduce, regression-proof | | refactor | Modernize without behavior change | | design-review | Visual/UI audit + screenshots | | architecture-review | Coupling, boundaries, patterns | | security-review | Auth, CVE, OWASP-style pass | | performance-review | Profiling, latency, N+1 | | release-check | Ship readiness | | prd-to-tasks | PRD → task decomposition | | hackathon | Narrow MVP + demo proof | | agent-readiness | .claude portfolio audit (read-only) | | tooling-review | MCP/CLI/auth readiness (read-only) | | skill-review | Skill quality / bloat (read-only) |

Programmatic API

const { generatePrompt } = require('@vaqif14/prompt-builder');

const result = generatePrompt('redesign checkout screen', {
  cwd: process.cwd(),
  mode: 'design-review',
  planFormat: 'visual',       // lean | human | visual
  visual: true,               // alias — writes artifacts on CLI; sets workflow section
  visualRecap: true,            // include Phase C in workflow + recap skill
  visualDir: 'plans/checkout', // override default plans/<slug>/
  maxTokens: 6000,
  discovery: discoveryResult,
});

// Agent IR
console.log(result.prompt);
console.log(result.validation.readiness);           // ready | draft
console.log(result.validation.solutionReadiness);
console.log(result.validation.planReadiness);

// Metadata
console.log(result.metadata.title, result.metadata.slug);
console.log(result.metadata.visualPlan.enabled);    // recommended?
console.log(result.metadata.visualPlan.artifacts);  // { dir, files, serveCommand }
console.log(result.metadata.humanPlan);             // MDX string when human/visual

Submodules: platformDetector, modeRouter, skillMatcher, planFormat, visualPlan, ecosystemSkills, antiSlop, anthropicSkills, workflowRouter, contextDiet, qualityRubric.

Validation V2

| Gate | Pts | |------|-----| | Skill discovery + stack-specific queries | 12 | | Platform + evidence | 12 | | Agent roster / task board | 12 | | Evidence gates | 12 | | Stop conditions + prompt contract + anti-slop | 12 | | Output schema actionable | 8 | | Not generic (no [stack] placeholders) | 8 | | Problem analysis + task plan present | 12 | | Workflow pattern | 4 | | Verification contract | 5 | | Length + stack profile blocks | 28 |

prompt-builder --validate my-prompt.md
npm run verify    # validate:data + test + eval

Token Economics

| Mechanism | Behavior | |-----------|----------| | Default budget | 6000 tokens (lean prompt only) | | Section priorities | P0 contracts always kept; visual workflow P2; designer rubric P3 | | Context diet | lean / ok / heavy + recommendedMaxTokens | | --full | Disable compression | | Lean task plan | ~40% smaller than verbose spec-kit prose | | Human/visual MDX | metadata or plans/ — never counted in prompt budget |

Claude Code Skill

ln -sf "$(pwd)" ~/.claude/skills/prompt-builder

The skill must read the codebase and fill PROBLEM ANALYSIS + TASK PLAN before handing the prompt back. For UI/architecture work, invoke /visual-plan with planText after the scaffold is filled. See SKILL.md Conclude hard-gate.

Data Architecture

| Layer | Location | |-------|----------| | Mode configs | data/templates/*.csv | | Stack profiles | data/stacks/*.csv | | Contracts | data/contracts/*.md + failure-conditions.csv | | Anti-slop patterns | data/anti-slop-patterns.csv | | Anthropic catalog | data/anthropic-skills-catalog.csv | | Ecosystem catalog | data/ecosystem-skills-catalog.csv | | Agent cards | data/agent-cards.csv | | Integrity | data/manifest.json (SHA-256; npm run manifest) |

Source modules: src/prompt-assembler.js, src/visual-plan.js, src/ecosystem-skills.js, src/plan-format.js.

Key CLI Flags

| Flag | Purpose | |------|---------| | --mode, --platform, --stack | Override detection | | --plan-format lean\|human\|visual | Plan artifact shape | | --visual | Alias for visual format; writes plans/<slug>/ on generate | | --visual-dir <path> | Custom artifact directory | | --visual-recap | Phase C recap + visual-recap skill in workflow | | --profile web\|backend\|mobile\|ai-agent\|hackathon | Capped install profile | | --discover / --no-discover | Ecosystem skill search | | --max-tokens, --full, --context-report | Budget control | | --compact, --json | Output shape | | --save, --save-draft, --save-auto, --force | Persistence | | --session-id, --list-sessions | Session continuity | | --record-outcome, --stats, --feedback-report | Local telemetry | | --trust-details <skill> | Static skill trust screen |

Philosophy

Each abstraction hides complexity behind a contract:

Assembly → C → Frameworks → Agents → Visual Plans

| Era | Human reasons about | Machine executes | |-----|---------------------|------------------| | Compilers | Source code | Assembly | | Web | Components + props | DOM | | Agents | Plans (goals, task rows, failure gates) | File edits + tests | | Agent-Native | Visual plans (wireframes, schema diffs, approval) | Same lean prompt |

Prompt Builder compiles the text IR. BuilderIO/skills compiles the visual IR. Execution stays in Claude Code, Cursor, or your harness — bounded by contracts, proven by evidence.

License

MIT