AI Development Workflow

Development is Cursor-first. Claude Code follows the same rules and skills via root AGENTS.md. Do not run a parallel process.

Judgment lives in planning and review. Implementation is incremental. See Engineering in the AI Era. Index this site once — Cursor Setup. Versioning and how to update skills: Cursor Skills.

FIRST is vendored from blockmatic/first. Install npx skills add blockmatic/first. Copy README.md, AGENTS.md, and ABOUT.md into _first/; keep FIRST.md and _first/basilic/ as this repo’s instance. Write overlays only for stations listed as In. Essays live on the FIRST site. Agents load _first/AGENTS.md, then _first/ABOUT.md, then _first/FIRST.md, then this repository's instructions and skills, then /f-* for the station in scope, then the instance listed in FIRST.md. FIRST does not replace this repository's Cursor-first workflow. Factory validation (pnpm validate) runs in the first repo. Two catalogs: blockmatic/first (/f-*) and blockmatic/basilic-skills (tech on GitHub; workflow is a local preview until main publishes the restored unprefixed tags). Installed playbooks live under .agents/skills/workflow/ (/plan-feature, dispatcher /workflow).

FIRST stations

Product, Journeys, Architecture, Data, API, Documentation, Workflow, Quality, Security, Operations. Pick one primary station. Overlays are deltas in _first/basilic/. Durable product facts: _first/basilic/PRODUCT.md. apps/docu is technical docs for adopters.

Sources of truth

Always-on rules point at apps/docu/content/docs/ for technical topics and _first/basilic/PRODUCT.md for product intent. Glob rules are constraints only. Read the matching file for the task. Do not @-attach MDX from rules or skills. Root AGENTS.md is the cross-harness stub.

Guidance hierarchy

Slash workflows

In Cursor chat, type / then the skill name.

• Enter — attach for this message only
• Option+Enter (Alt+Enter) — pin for the session

Use /workflow (local preview dispatcher) to list the catalog, /workflow <shortcut> to route a task, or the full /<name> to load a playbook directly. FIRST /f-* remains the separate decision catalog.

An empty /workflow lists options; an unknown token reports the available names. Neither starts work. /build ends with verified local changes. /exec-push explicitly requests implementation, full validation, commit, push, and a described PR. No workflow implies merge or deployment.

Names match folders under .agents/skills/workflow/, such as plan-feature. Names from /b-* chats can be translated; they are not separate installed aliases. Update pinned prompts and reload discovery after installing. When a harness does not expose the slash menu, read .agents/skills/workflow/SKILL.md and the named child directly. Do not create another skills tree.

Workflow

1. Plan — /workflow plan for non-trivial work. Read existing implementation and docs; list goals, assumptions, acceptance conditions, dependencies, and verification per slice. Planning alone does not create a branch or implement code.
2. Review the plan — /review-plan checks scope and ordering. Resolve consequential decisions through FIRST; continue routine work already authorized.
3. Implement — /workflow build delivers complete slices and runs affected checks. Preserve unrelated changes and generated-source ownership. Update matching docs when behavior changes.
4. Review the change — /workflow review returns evidenced findings and verification limits. Reviews stay read-only unless fixes are requested.
5. Publish when requested — /workflow commit, /workflow push, or /workflow pr perform their named actions. /exec-push combines the implementation-to-PR path and requires pnpm qa.
6. Learn — /workflow retro identifies concrete improvements; changed conventions belong in existing durable documentation.

Tech skills (fastify-v5, next-v16, vercel-react-v1) load when relevant. FIRST owns product and cross-cutting decisions; the workflow does not add another backlog or quality policy.

The generator retains this catalog and rewrites its documentation pointers to the adopter’s local docs snapshot. /release-review is advisory and preserves the release tooling’s human gates.

Checklists and evidence

The core playbooks use inputs, steps, verification, and a handoff. Reviews inspect correctness, clarity, architecture, security, performance, and the verification claims. Debugging connects a reproduction to its cause and repeats the original scenario after a fix.

Shared completion evidence lives inside the installed workflow/references/ directory. Record checks as passed, failed, not run, or not applicable with a reason. A type check alone does not verify a browser interaction. Documentation changes need proportionate checks; TDD remains explicit through /use-tdd or repository requirements.

The selective adaptation of Addy's skills is documented in the basilic-skills checkout (not yet published on GitHub). See Cursor Skills for local preview and publication status.

Models (30 Aug 2026)

In-app chat (Fastify /ai/chat) defaults to Claude Haiku 4.5 — product model, not this workflow. Pass model: "sonnet" for Sonnet 4.6. See Self-Hosted LLM.

CodeRabbit reviews PRs against project standards. Local gates: Biome, ESLint, pre-commit security.

Point agents at MDX: Using the patterns from @api, add an endpoint…

Related

• Cursor Setup — indexed docs and MCP
• Cursor Skills — versioning, vendor and overlay, inventory
• Repo .cursor/README.md — short file index (points here for how to work)