Quick Start Guide

You installed 57 skills and ran init-agents. Now what? This guide shows you how to work with your agent effectively using the skills you have.

Your First Session

After init-agents, describe what you want to build. The agent auto-detects which skills to load. Here's what the first feature looks like from your side:

1. You describe the task — "Build a login page with email and password." The agent matches this to frontend-web, security-and-hardening, and test-driven-development.
2. Agent loads skills — The skill gate logs which skills were consulted. You'll see this in the pre-commit output.
3. Agent writes SPEC.md — The spec defines scope, stack, acceptance criteria, and boundaries. The agent asks you questions to fill gaps.
4. You review the plan — The agent presents a DECISION POINT: "Here's the spec. Shall I proceed?" Read it. Say "yes" or request changes.
5. Agent builds incrementally — One slice at a time. Each slice includes code + tests. After each slice, the agent runs tests.
6. Tests run automatically — Pre-commit Gate 14 runs bash tests/run-all.sh before every commit. If tests fail, the commit blocks.
7. Agent presents commit decision — You see a DECISION POINT with the diff summary. Type "yes commit" to approve. The TDD gate verifies tests accompany code.

How Skills Activate

Skills load automatically when the agent detects a matching task. You don't call skills — you describe what you need.

You Say	Skill That Loads
"Add a login page"	frontend-web + spec-driven-development + test-driven-development
"Build a REST API"	backend-api-mastery + api-and-interface-design
"Create a CLI tool"	cli-tools + spec-driven-development
"Review this code"	code-review-and-quality
"Fix this bug"	debugging-and-error-recovery
"Write tests"	test-driven-development
"Deploy to production"	shipping-and-launch + ci-cd-and-automation
"Design a landing page"	frontend-web + critique-skill + polish-skill

Pro tip: If auto-detection misses, say "load the [skill-name] skill" or "use TDD for this." You can also say "what skill are you using?" to see what's loaded.

The 6 Phases from Your Side

Every feature follows the same flow. Your role changes per phase:

Phase	Agent Does	You Do
DEFINE	Writes SPEC.md. Asks discovery questions.	Read the spec. Confirm or request changes. Say "yes" to proceed.
PLAN	Breaks work into tasks with acceptance criteria.	Review the task list. Confirm or reorder.
BUILD	Implements one slice. Writes tests. Verifies.	Review each increment. Reject if it doesn't match spec.
VERIFY	Runs test suite. Checks gates.	Wait. Fix if a gate blocks. Tests are mechanical — trust them.
REVIEW	Reviews its own code: security, perf, quality.	Read the review. Approve or request changes.
SHIP	Commits. Pushes. CI runs.	Type "yes commit" when you see the DECISION POINT.

Guardian Pattern — Your Role in Quality

Before every mutation (commit, push, merge), the agent must present a DECISION POINT block. This is your opportunity to review before giving consent.

DECISION POINT — Commit
  Plan approved: ✅
  Manifest: 3 files changed (src/login.ts, src/login.test.ts, SPEC.md)
  Tests: 5/5 passed (TDD gate: ✅)

  → Approve this commit? Reply "yes commit" to proceed.

Rules:

• Valid responses: "yes", "yes commit", "sí", "proceed", "adelante", "let's go"
• Invalid responses: "ok", "sure", "mmhm", "continue" — the agent will ask again
• Plan ≠ Commit: Approving the plan does NOT approve the commit. Each mutation is a separate decision.
• You can reject: Say "no" or "change X" to send it back. The agent cannot proceed without your consent.

Common Scenarios

Building a New Feature

1. Describe the feature: "Add a password reset flow"
2. Agent writes SPEC.md → you approve
3. Agent plans tasks → you confirm
4. Agent builds + tests each slice → you review
5. Tests run → pre-commit gates pass → "yes commit"

Fixing a Bug

1. Describe the bug: "The login button doesn't work on mobile"
2. Agent loads debugging-and-error-recovery → inspects root cause
3. Agent writes a failing test that reproduces the bug (TDD)
4. Agent fixes the code → test passes
5. Pre-commit gates validate → "yes commit"

Refactoring Code

1. Say "Refactor this component to be simpler"
2. Agent loads code-simplification → analyzes complexity
3. Agent applies Beck's 4 rules: passes tests, reveals intention, no duplication, fewest elements
4. Tests verify behavior didn't change → "yes commit"

Tips for Better Results

• Be specific about your stack. "Build a React app using Next.js 14 with TypeScript" gets better results than "build an app."
• Use skill names when it matters. "Load the test-driven-development skill" forces TDD. "Use code-review-and-quality" triggers a full review.
• Read DECISION POINTs carefully. The agent describes what it will do. If it sounds wrong, say "no" or "change X."
• If the agent loads the wrong skill, say "load the [correct-skill] skill instead." The skill gate adjusts.
• Check which gates ran. After a commit, the pre-commit output shows all 15 gates (0-14). If one skipped when it shouldn't, investigate.
• Run tests before creating a PR. Pre-commit Gate 14 catches failures. If you skip with SKIP_TEST_RUNNER, CI catches it.