Build Your First Feature

Learn the AI-driven development workflow by building a complete feature. This tutorial walks through the full lifecycle — from invoking a skill, through TDD implementation, to auto-generated documentation on commit.

---

Prerequisites

• Completed setup and AI framework configuration (see Setup Guide)
• Development server running
• An AI coding tool installed (Claude Code, Cursor, Windsurf, or similar)

---

The Development Lifecycle

The framework follows a skill-based software development lifecycle (SDLC). Each phase has a matching Agent Skill — a structured workflow the AI follows when you invoke it by name.

specify -> plan -> build -> manual-qa -> review -> document

Phase	Skill	Purpose
Define	specify	Create a PRD (WHAT to build)
Define	plan	Decompose into tasks (HOW to build)
Build	new-feature, fix-bug, etc.	Implement with TDD
Verify	manual-qa	Smoke-test in the browser
Review	code-review, design-review	Audit quality
Document	readme-updater	Update module docs

Complex features use all phases. Simple features can skip the Define phase and go straight to Build — just describe the feature inline. For complex features, see PRD Workflow.

For the full skill list and recovery prompts, see AI Prompt Library.

---

Step 1: Enter Plan Mode

Start by entering plan mode in your AI coding tool:

• Claude Code: Press Shift+Tab
• Cursor: Type /plan or use Composer mode
• Windsurf: Use Cascade planning
• Other tools: Check your tool’s planning documentation

Plan mode loads the AGENTS.md core rules and activates scoped rules for the files you will edit. For details on how this works, see AI Framework.

---

Step 2: Invoke the Skill

Tell the AI to use a skill by name. For example, to build a new feature:

Use the new-feature skill to build an Items List feature.

What it does:
- Display a list of items belonging to the current organization
- Each item has a name and description
- Show items in a table format
- Handle empty state when no items exist

Always invoke skills by name. Writing "Use the new-feature skill to..." guarantees the AI loads the full workflow, including pre-flight checks, the three-gate system, and TDD steps. Without the explicit skill name, the AI may skip project patterns.

The Pre-Flight Block

The skill prints a pre-flight block confirming its research before starting implementation:

Pre-flight:
  Always active: development, nfr, mcp-tools
  Task rules: database, api-routes, ui-components, testing
  Skill: new-feature
  READMEs:
    - Service layer README (delegation patterns)
    - Component library README (UI catalog)
  Patterns: Existing CRUD routes (auth + scoping)
  PRD: not needed
  Security: Zod on all inputs, auth + organizationId scoping

The pre-flight block shows which rules, patterns, and READMEs the AI has loaded. If this block is missing or the READMEs section is empty, prompt the AI to follow the skill’s Gate 1 checklist before proceeding.

---

Step 3: Review and Approve the Plan

Before implementation begins, the AI presents its plan. Check that the plan covers:

• Database: Schema changes with organization-level scoping
• Testing: TDD approach (tests before implementation)
• API: Authentication and input validation
• UI: Design system compliance, empty states, loading states

If the plan looks incomplete, ask the AI to revise. Once satisfied, approve with: "Looks good! Proceed with implementation."

---

Step 4: AI Implements with TDD

The skill’s Gate 2 enforces test-driven development. Tests are written before implementation at each layer.

The AI follows this sequence:

1. Database model — Adds the schema definition, then prompts you to run the migration
2. API tests — Writes tests for the API route handler
3. API implementation — Implements the route handler until tests pass
4. Page tests — Writes tests for the UI page component
5. Page implementation — Implements the page until tests pass

At each step, the AI writes tests first and then writes the implementation to make them pass.

If the AI gets stuck, you can ask it to use Context7 MCP for up-to-date library documentation, or use Chrome DevTools MCP to debug browser-side issues. See MCP Tools Setup for details.

---

Step 5: Verify the Implementation

Run the full test suite:

make test

All tests should pass. Then verify manually by visiting the new page in your browser while the dev server is running.

If tests are failing, paste the error output to the AI:

Tests are failing with: [paste error]
Please fix the issue.

Optional: Code Review

For production features, run review skills before committing:

"Use the code-review skill to audit the items feature."
"Use the design-review skill to check accessibility and design system compliance."

Review skills produce severity-based reports (Critical / Warning / Suggestion). Fix any Critical findings before proceeding.

---

Step 6: Commit with Auto-Documentation

This is where the framework’s documentation automation activates.

Stage and commit your changes:

git add .
git commit -m "feat: add items list feature"

What happens automatically on commit:

1. The post-commit hook runs the documentation generator, which creates README skeletons for new routes and modules
2. The hook output instructs the AI to invoke the readme-updater skill to fill skeletons with business logic descriptions
3. In agentic tools (Claude Code, Cursor, etc.), the AI detects this output and invokes the skill automatically

If the AI does not auto-invoke, prompt it manually: "Use the readme-updater skill to update READMEs for my recent changes."

Commit the generated documentation:

git add .
git commit -m "docs: auto-update feature documentation"

The pre-push hook validates all documentation before pushing, ensuring docs never drift from the codebase.

---

Building Your Own Features

Simple feature — invoke the build skill directly:

Use the new-feature skill to build [description of what it does].

Complex feature — start with Define, then Build:

1. "Use the specify skill to create a PRD for [feature]."
2. "Use the plan skill to decompose PRD-[name] into tasks."
3. "Use the new-feature skill to implement Task 1: [title]."

Bug fix:

Use the fix-bug skill to fix [description of the bug].

---

Key Takeaways

The framework workflow is: invoke skill by name -> three-gate system (context, TDD, completion) -> commit -> auto-docs.

1. Always invoke skills by name. This guarantees the full workflow loads, including pre-flight checks and pattern discovery.
2. Trust the framework. Gate 1 automatically loads the relevant patterns, scoped rules, and READMEs for your task.
3. Reference existing features. When building something similar to an existing feature, tell the AI: “Follow patterns from [feature].”
4. Commit frequently. Git hooks keep documentation in sync with every commit.

This same workflow scales to every feature you build.

---

Next Steps

• Design Customization — Customize brand colors, fonts, and spacing
• AI Prompt Library — Full skill table and recovery prompts
• PRD Workflow — When and how to use PRDs for complex features