R Rebeauty Atlas +7,670 today
← Back to list

The Alchemist codes no more. Now He writes the SPECs that makes the SOFTWARE.

The days of searching for the magical stone is over a new discovery has shown that Large Language Models coupled with their agentic…

edbert kwesi · 2026-06-06 15:30 · 0 claps · 26.9 min read
#google-antigravity-skills #large-language-models #github-spec-kit #spec-driven-development
Open on Medium ↗
Wiki topics: LLM · Large Language Models AGT · AI Agents 🔓 · Open Source

The Alchemist codes no more. Now He writes the SPECs that makes the SOFTWARE.

The days of searching for the magical stone is over a new discovery has shown that Large Language Models coupled with their agentic instructions are capable of writing the DNA code of the very stone the alchemist is search of with a bit of precise instruction well specified software can now be generated quickly and easily but the alchemist must know the formula the recipe that make-up an excellent software.

With specificity comes precision the concept of Spec Driven Development is about precisely crafting detailed rich context for a Large Language Model to follow during it execution process. To start-off lets combine spec Driven Development with Google’s Antigravity plus ADK to build an Agent that is able to make restaurant orders and book reservations as well.

Developing restaurant concierge application with reservation booking added through a complete SDD cycle using Google’s Antigravity

Google Cloud is the main platform for this project. make sure you have uv, git, gcloud, and npm installed on your machine or whichever is your choice cloud or virtual machine.

The guide below enables you to clone project repo antigravity IDE authenticate with Google cloud , setup your environment and enable API’s

git clone https://github.com/alphinside/sdd-adk-antigravity-starter.git sdd-adk-agents-agy
cd sdd-adk-agents-agy

git remote remove origin

gcloud auth login
gcloud auth application-default login

echo "GOOGLE_CLOUD_LOCATION=global" > .env
echo "REGION=us-central1" >> .env

curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh
bash setup_verify_trial_project.sh && source .env

gcloud services enable \
  aiplatform.googleapis.com \
  sqladmin.googleapis.com \
  compute.googleapis.com \
  cloudresourcemanager.googleapis.com

uv sync

cat > restaurant_concierge/.env <<EOF
GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True
EOF

export DB_PASSWORD=codelabpassword
echo "DB_PASSWORD=${DB_PASSWORD}" >> .env

chmod +x scripts/setup_database.sh
./scripts/setup_database.sh > database_setup.log 2>&1 &

Architectural overview

The challenge is to develop a restaurant app which has an Agent embbeded with the app. This agent should be able to book tables and make reservations as you command. so we therefore need something to hold the data and also a way to query the data. Cloud SQL to hold data, then an MCP toolbox connected to the database plus vertex AI for embedding data inference server.

Part two: Spec Driven Development.

Speck-kit is a python package designed for the spec Driven Developement software paradigm. Made up of markdown files that enable you to write the specifications you want for your software. Here is how a spec-kit flow hierarchy looks like.

Each file named here has a role play in guiding the Large Language model in doing what we want.

Below are the workflow files starting from spec-kit.specify.md file to spec-kit.implement md. These files contain instructional guides and steps that enable the Large Language model to do as you have precisely described in your prompts. For example. if a user describes in his/her prompt that a particular feature be implemented immediately the spec-kit.implement script is activated for the feature to be built.

Below is the spec-kit.specify.md script which contains instructions on the feature specifications you want to implement.

---
description: Create or update the feature specification from a natural language feature description.
handoffs: 
  - label: Build Technical Plan
    agent: speckit.plan
    prompt: Create a plan for the spec. I am building with...
  - label: Clarify Spec Requirements
    agent: speckit.clarify
    prompt: Clarify specification requirements
    send: true
---

## User Input

```text
$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

The text the user typed after /speckit.specify in the triggering message is the feature description. Assume you always have it available in this conversation even if {{args}} appears literally below. Do not ask the user to repeat it unless they provided an empty command.

Given that feature description, do this:

  1. Generate a concise short name (2-4 words) for the branch:

    • Analyze the feature description and extract the most meaningful keywords
    • Create a 2-4 word short name that captures the essence of the feature
    • Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
    • Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
    • Keep it concise but descriptive enough to understand the feature at a glance
    • Examples:
      • "I want to add user authentication" → "user-auth"
      • "Implement OAuth2 integration for the API" → "oauth2-api-integration"
      • "Create a dashboard for analytics" → "analytics-dashboard"
      • "Fix payment processing timeout bug" → "fix-payment-timeout"

  2. Check for existing branches before creating new one:

    a. First, fetch all remote branches to ensure we have the latest information:

       git fetch --all --prune

    b. Find the highest feature number across all sources for the short-name:

    • Remote branches: git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'
    • Local branches: git branch | grep -E '^[* ]*[0-9]+-<short-name>$'
    • Specs directories: Check for directories matching specs/[0-9]+-<short-name>

    c. Determine the next available number:

    • Extract all numbers from all three sources
    • Find the highest number N
    • Use N+1 for the new branch number

    d. Run the script .specify/scripts/bash/create-new-feature.sh --json "{{args}}" with the calculated number and short-name:

    • Pass --number N+1 and --short-name "your-short-name" along with the feature description
    • Bash example: .specify/scripts/bash/create-new-feature.sh --json "{{args}}" --json --number 5 --short-name "user-auth" "Add user authentication"
    • PowerShell example: .specify/scripts/bash/create-new-feature.sh --json "{{args}}" -Json -Number 5 -ShortName "user-auth" "Add user authentication"

    IMPORTANT:

    • Check all three sources (remote branches, local branches, specs directories) to find the highest number
    • Only match branches/directories with the exact short-name pattern
    • If no existing branches/directories found with this short-name, start with number 1
    • You must only ever run this script once per feature
    • The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for
    • The JSON output will contain BRANCH_NAME and SPEC_FILE paths
    • For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot")

  3. Load .specify/templates/spec-template.md to understand required sections.

  4. Follow this execution flow:

    1. Parse user description from Input If empty: ERROR "No feature description provided"
    2. Extract key concepts from description Identify: actors, actions, data, constraints
    3. For unclear aspects:
      • Make informed guesses based on context and industry standards
      • Only mark with [NEEDS CLARIFICATION: specific question] if:
        • The choice significantly impacts feature scope or user experience
        • Multiple reasonable interpretations exist with different implications
        • No reasonable default exists
      • LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total
      • Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
    4. Fill User Scenarios & Testing section If no clear user flow: ERROR "Cannot determine user scenarios"
    5. Generate Functional Requirements Each requirement must be testable Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
    6. Define Success Criteria Create measurable, technology-agnostic outcomes Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion) Each criterion must be verifiable without implementation details
    7. Identify Key Entities (if data involved)
    8. Return: SUCCESS (spec ready for planning)

  5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.

  6. Specification Quality Validation: After writing the initial spec, validate it against quality criteria:

    a. Create Spec Quality Checklist: Generate a checklist file at FEATURE_DIR/checklists/requirements.md using the checklist template structure with these validation items:

       # Specification Quality Checklist: [FEATURE NAME]

   **Purpose**: Validate specification completeness and quality before proceeding to planning
   **Created**: [DATE]
   **Feature**: [Link to spec.md]

   ## Content Quality

   - [ ] No implementation details (languages, frameworks, APIs)
   - [ ] Focused on user value and business needs
   - [ ] Written for non-technical stakeholders
   - [ ] All mandatory sections completed

   ## Requirement Completeness

   - [ ] No [NEEDS CLARIFICATION] markers remain
   - [ ] Requirements are testable and unambiguous
   - [ ] Success criteria are measurable
   - [ ] Success criteria are technology-agnostic (no implementation details)
   - [ ] All acceptance scenarios are defined
   - [ ] Edge cases are identified
   - [ ] Scope is clearly bounded
   - [ ] Dependencies and assumptions identified

   ## Feature Readiness

   - [ ] All functional requirements have clear acceptance criteria
   - [ ] User scenarios cover primary flows
   - [ ] Feature meets measurable outcomes defined in Success Criteria
   - [ ] No implementation details leak into specification

   ## Notes

   - Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`

    b. Run Validation Check: Review the spec against each checklist item:

    • For each item, determine if it passes or fails
    • Document specific issues found (quote relevant spec sections)

    c. Handle Validation Results:

    • If all items pass: Mark checklist complete and proceed to step 6

    • If items fail (excluding [NEEDS CLARIFICATION]):

      1. List the failing items and specific issues
      2. Update the spec to address each issue
      3. Re-run validation until all items pass (max 3 iterations)
      4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user

    • If [NEEDS CLARIFICATION] markers remain:

      1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec

      2. LIMIT CHECK: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest

      3. For each clarification needed (max 3), present options to user in this format:

        ## Question [N]: [Topic]

**Context**: [Quote relevant spec section]

**What we need to know**: [Specific question from NEEDS CLARIFICATION marker]

**Suggested Answers**:

| Option | Answer | Implications |
|--------|--------|--------------|
| A      | [First suggested answer] | [What this means for the feature] |
| B      | [Second suggested answer] | [What this means for the feature] |
| C      | [Third suggested answer] | [What this means for the feature] |
| Custom | Provide your own answer | [Explain how to provide custom input] |

**Your choice**: _[Wait for user response]_

      4. CRITICAL - Table Formatting: Ensure markdown tables are properly formatted:

        • Use consistent spacing with pipes aligned
        • Each cell should have spaces around content: | Content | not |Content|
        • Header separator must have at least 3 dashes: |--------|
        • Test that the table renders correctly in markdown preview

      5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)

      6. Present all questions together before waiting for responses

      7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")

      8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer

      9. Re-run validation after all clarifications are resolved

    d. Update Checklist: After each validation iteration, update the checklist file with current pass/fail status

  7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (/speckit.clarify or /speckit.plan).

NOTE: The script creates and checks out the new branch and initializes the spec file before writing.

General Guidelines

Quick Guidelines

  • Focus on WHAT users need and WHY.
  • Avoid HOW to implement (no tech stack, APIs, code structure).
  • Written for business stakeholders, not developers.
  • DO NOT create any checklists that are embedded in the spec. That will be a separate command.

Section Requirements

  • Mandatory sections: Must be completed for every feature
  • Optional sections: Include only when relevant to the feature
  • When a section doesn't apply, remove it entirely (don't leave as "N/A")

For AI Generation

When creating this spec from a user prompt:

  1. Make informed guesses: Use context, industry standards, and common patterns to fill gaps
  2. Document assumptions: Record reasonable defaults in the Assumptions section
  3. Limit clarifications: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
    • Significantly impact feature scope or user experience
    • Have multiple reasonable interpretations with different implications
    • Lack any reasonable default
  4. Prioritize clarifications: scope > security/privacy > user experience > technical details
  5. Think like a tester: Every vague requirement should fail the "testable and unambiguous" checklist item
  6. Common areas needing clarification (only if no reasonable default exists):
    • Feature scope and boundaries (include/exclude specific use cases)
    • User types and permissions (if multiple conflicting interpretations possible)
    • Security/compliance requirements (when legally/financially significant)

Examples of reasonable defaults (don't ask about these):

  • Data retention: Industry-standard practices for the domain
  • Performance targets: Standard web/mobile app expectations unless specified
  • Error handling: User-friendly messages with appropriate fallbacks
  • Authentication method: Standard session-based or OAuth2 for web apps
  • Integration patterns: RESTful APIs unless specified otherwise

Success Criteria Guidelines

Success criteria must be:

  1. Measurable: Include specific metrics (time, percentage, count, rate)
  2. Technology-agnostic: No mention of frameworks, languages, databases, or tools
  3. User-focused: Describe outcomes from user/business perspective, not system internals
  4. Verifiable: Can be tested/validated without knowing implementation details

Good examples:

  • "Users can complete checkout in under 3 minutes"
  • "System supports 10,000 concurrent users"
  • "95% of searches return results in under 1 second"
  • "Task completion rate improves by 40%"

Bad examples (implementation-focused):

  • "API response time is under 200ms" (too technical, use "Users see results instantly")
  • "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
  • "React components render efficiently" (framework-specific)
  • "Redis cache hit rate above 80%" (technology-specific)

Below is the speckit.clarify.md file containing instructions that enable the model to identify your unstated intentions meaning its able to figure out hidden part of what you intend to do from the user prompt.

---
description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
handoffs: 
  - label: Build Technical Plan
    agent: speckit.plan
    prompt: Create a plan for the spec. I am building with...
---

## User Input

```text
$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.

Note: This clarification workflow is expected to run (and be completed) BEFORE invoking /speckit.plan. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.

Execution steps:

  1. Run .specify/scripts/bash/check-prerequisites.sh --json --paths-only from repo root once (combined --json --paths-only mode / -Json -PathsOnly). Parse minimal JSON payload fields:

    • FEATURE_DIR
    • FEATURE_SPEC
    • (Optionally capture IMPL_PLAN, TASKS for future chained flows.)
    • If JSON parsing fails, abort and instruct user to re-run /speckit.specify or verify feature branch environment.
    • For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").

  2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).

    Functional Scope & Behavior:

    • Core user goals & success criteria
    • Explicit out-of-scope declarations
    • User roles / personas differentiation

    Domain & Data Model:

    • Entities, attributes, relationships
    • Identity & uniqueness rules
    • Lifecycle/state transitions
    • Data volume / scale assumptions

    Interaction & UX Flow:

    • Critical user journeys / sequences
    • Error/empty/loading states
    • Accessibility or localization notes

    Non-Functional Quality Attributes:

    • Performance (latency, throughput targets)
    • Scalability (horizontal/vertical, limits)
    • Reliability & availability (uptime, recovery expectations)
    • Observability (logging, metrics, tracing signals)
    • Security & privacy (authN/Z, data protection, threat assumptions)
    • Compliance / regulatory constraints (if any)

    Integration & External Dependencies:

    • External services/APIs and failure modes
    • Data import/export formats
    • Protocol/versioning assumptions

    Edge Cases & Failure Handling:

    • Negative scenarios
    • Rate limiting / throttling
    • Conflict resolution (e.g., concurrent edits)

    Constraints & Tradeoffs:

    • Technical constraints (language, storage, hosting)
    • Explicit tradeoffs or rejected alternatives

    Terminology & Consistency:

    • Canonical glossary terms
    • Avoided synonyms / deprecated terms

    Completion Signals:

    • Acceptance criteria testability
    • Measurable Definition of Done style indicators

    Misc / Placeholders:

    • TODO markers / unresolved decisions
    • Ambiguous adjectives ("robust", "intuitive") lacking quantification

    For each category with Partial or Missing status, add a candidate question opportunity unless:

    • Clarification would not materially change implementation or validation strategy
    • Information is better deferred to planning phase (note internally)

  3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:

    • Maximum of 10 total questions across the whole session.
    • Each question must be answerable with EITHER:
      • A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
      • A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
    • Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
    • Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
    • Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
    • Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
    • If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.

  4. Sequential questioning loop (interactive):

    • Present EXACTLY ONE question at a time.

    • For multiple‑choice questions:

      • Analyze all options and determine the most suitable option based on:
        • Best practices for the project type
        • Common patterns in similar implementations
        • Risk reduction (security, performance, maintainability)
        • Alignment with any explicit project goals or constraints visible in the spec
      • Present your recommended option prominently at the top with clear reasoning (1-2 sentences explaining why this is the best choice).
      • Format as: **Recommended:** Option [X] - <reasoning>
      • Then render all options as a Markdown table:
      Option Description
      A <Option A description>
      B <Option B description>
      C <Option C description> (add D/E as needed up to 5)
      Short Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate)
      • After the table, add: You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.

    • For short‑answer style (no meaningful discrete options):

      • Provide your suggested answer based on best practices and context.
      • Format as: **Suggested:** <your proposed answer> - <brief reasoning>
      • Then output: Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.

    • After the user answers:

      • If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
      • Otherwise, validate the answer maps to one option or fits the <=5 word constraint.
      • If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
      • Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.

    • Stop asking further questions when:

      • All critical ambiguities resolved early (remaining queued items become unnecessary), OR
      • User signals completion ("done", "good", "no more"), OR
      • You reach 5 asked questions.

    • Never reveal future queued questions in advance.

    • If no valid questions exist at start, immediately report no critical ambiguities.

  5. Integration after EACH accepted answer (incremental update approach):

    • Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
    • For the first integrated answer in this session:
      • Ensure a ## Clarifications section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
      • Under it, create (if not present) a ### Session YYYY-MM-DD subheading for today.
    • Append a bullet line immediately after acceptance: - Q: <question> → A: <final answer>.
    • Then immediately apply the clarification to the most appropriate section(s):
      • Functional ambiguity → Update or add a bullet in Functional Requirements.
      • User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
      • Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
      • Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
      • Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
      • Terminology conflict → Normalize term across spec; retain original only if necessary by adding (formerly referred to as "X") once.
    • If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
    • Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
    • Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
    • Keep each inserted clarification minimal and testable (avoid narrative drift).

  6. Validation (performed after EACH write plus final pass):

    • Clarifications session contains exactly one bullet per accepted answer (no duplicates).
    • Total asked (accepted) questions ≤ 5.
    • Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
    • No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
    • Markdown structure valid; only allowed new headings: ## Clarifications, ### Session YYYY-MM-DD.
    • Terminology consistency: same canonical term used across all updated sections.

  7. Write the updated spec back to FEATURE_SPEC.

  8. Report completion (after questioning loop ends or early termination):

    • Number of questions asked & answered.
    • Path to updated spec.
    • Sections touched (list names).
    • Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
    • If any Outstanding or Deferred remain, recommend whether to proceed to /speckit.plan or run /speckit.clarify again later post-plan.
    • Suggested next command.

Behavior rules:

  • If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
  • If spec file missing, instruct user to run /speckit.specify first (do not create a new spec here).
  • Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
  • Avoid speculative tech stack questions unless the absence blocks functional clarity.
  • Respect user early termination signals ("stop", "done", "proceed").
  • If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
  • If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.

Context for prioritization: {{args}} """


*Below is speckit.plan.md. This guides the model to devise a strategy for building what the user has requested and does this in stages.*

  • description: Execute the implementation planning workflow using the plan template to generate design artifacts. handoffs:

  • label: Create Tasks agent: speckit.tasks prompt: Break the plan into tasks send: true

  • label: Create Checklist agent: speckit.checklist prompt: Create a checklist for the following domain...

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

  1. Setup: Run .specify/scripts/bash/setup-plan.sh --json from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").

  2. Load context: Read FEATURE_SPEC and .specify/memory/constitution.md. Load IMPL_PLAN template (already copied).

  3. Execute plan workflow: Follow the structure in IMPL_PLAN template to:

    • Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
    • Fill Constitution Check section from constitution
    • Evaluate gates (ERROR if violations unjustified)
    • Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
    • Phase 1: Generate data-model.md, contracts/, quickstart.md
    • Phase 1: Update agent context by running the agent script
    • Re-evaluate Constitution Check post-design

  4. Stop and report: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.

Phases

Phase 0: Outline & Research

  1. Extract unknowns from Technical Context above:

    • For each NEEDS CLARIFICATION → research task
    • For each dependency → best practices task
    • For each integration → patterns task

  2. Generate and dispatch research agents:

    For each unknown in Technical Context:
  Task: "Research {unknown} for {feature context}"
For each technology choice:
  Task: "Find best practices for {tech} in {domain}"

  3. Consolidate findings in research.md using format:

    • Decision: [what was chosen]
    • Rationale: [why chosen]
    • Alternatives considered: [what else evaluated]

Output: research.md with all NEEDS CLARIFICATION resolved

Phase 1: Design & Contracts

Prerequisites: research.md complete

  1. Extract entities from feature spec → data-model.md:

    • Entity name, fields, relationships
    • Validation rules from requirements
    • State transitions if applicable

  2. Generate API contracts from functional requirements:

    • For each user action → endpoint
    • Use standard REST/GraphQL patterns
    • Output OpenAPI/GraphQL schema to /contracts/

  3. Project context update → .agents/rules/project-context.md:

    Update or create .agents/rules/project-context.md using the template at .specify/templates/project-context-template.md.

    Update rules:

    • If file doesn't exist, create from template with information from this feature
    • If file exists, update only relevant sections:
      • Add new technologies from Technical Context (avoid duplicates)
      • Add new entities from data-model.md to Data Model Overview
      • Add new integrations from contracts/ to External Integrations
      • Prepend feature to Recent Features (keep last 5)
      • Update Last Updated date and Updated By fields
    • Preserve content between <!-- MANUAL ADDITIONS START --> and <!-- MANUAL ADDITIONS END -->
    • For Project Identity, only fill if empty (don't overwrite existing values)

Output: data-model.md, /contracts/*, quickstart.md, .agents/rules/project-context.md

Key rules

  • Use absolute paths
  • ERROR on gate failures or unresolved clarifications

Speckit.task file contains a set of instructions that break plan into ordered actionable steps.

---
description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
handoffs: 
  - label: Analyze For Consistency
    agent: speckit.analyze
    prompt: Run a project analysis for consistency
    send: true
  - label: Implement Project
    agent: speckit.implement
    prompt: Start the implementation in phases
    send: true
---

## User Input

```text
$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

  1. Setup: Run .specify/scripts/bash/check-prerequisites.sh --json from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").

  2. Load design documents: Read from FEATURE_DIR:

    • Required: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
    • Optional: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)
    • Note: Not all projects have all documents. Generate tasks based on what's available.

  3. Execute task generation workflow:

    • Load plan.md and extract tech stack, libraries, project structure
    • Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
    • If data-model.md exists: Extract entities and map to user stories
    • If contracts/ exists: Map endpoints to user stories
    • If research.md exists: Extract decisions for setup tasks
    • Generate tasks organized by user story (see Task Generation Rules below)
    • Generate dependency graph showing user story completion order
    • Create parallel execution examples per user story
    • Validate task completeness (each user story has all needed tasks, independently testable)

  4. Generate tasks.md: Use .specify/templates/tasks-template.md as structure, fill with:

    • Correct feature name from plan.md
    • Phase 1: Setup tasks (project initialization)
    • Phase 2: Foundational tasks (blocking prerequisites for all user stories)
    • Phase 3+: One phase per user story (in priority order from spec.md)
    • Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
    • Final Phase: Polish & cross-cutting concerns
    • All tasks must follow the strict checklist format (see Task Generation Rules below)
    • Clear file paths for each task
    • Dependencies section showing story completion order
    • Parallel execution examples per story
    • Implementation strategy section (MVP first, incremental delivery)

  5. Report: Output path to generated tasks.md and summary:

    • Total task count
    • Task count per user story
    • Parallel opportunities identified
    • Independent test criteria for each story
    • Suggested MVP scope (typically just User Story 1)
    • Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)

Context for task generation: $ARGUMENTS

The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.

Task Generation Rules

CRITICAL: Tasks MUST be organized by user story to enable independent implementation and testing.

Tests are OPTIONAL: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.

Checklist Format (REQUIRED)

Every task MUST strictly follow this format:

- [ ] [TaskID] [P?] [Story?] Description with file path

Format Components:

  1. Checkbox: ALWAYS start with - [ ] (markdown checkbox)
  2. Task ID: Sequential number (T001, T002, T003...) in execution order
  3. [P] marker: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
  4. [Story] label: REQUIRED for user story phase tasks only
    • Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
    • Setup phase: NO story label
    • Foundational phase: NO story label
    • User Story phases: MUST have story label
    • Polish phase: NO story label
  5. Description: Clear action with exact file path

Examples:

  • ✅ CORRECT: - [ ] T001 Create project structure per implementation plan
  • ✅ CORRECT: - [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py
  • ✅ CORRECT: - [ ] T012 [P] [US1] Create User model in src/models/user.py
  • ✅ CORRECT: - [ ] T014 [US1] Implement UserService in src/services/user_service.py
  • ❌ WRONG: - [ ] Create User model (missing ID and Story label)
  • ❌ WRONG: T001 [US1] Create model (missing checkbox)
  • ❌ WRONG: - [ ] [US1] Create User model (missing Task ID)
  • ❌ WRONG: - [ ] T001 [US1] Create model (missing file path)

Task Organization

  1. From User Stories (spec.md) - PRIMARY ORGANIZATION:

    • Each user story (P1, P2, P3...) gets its own phase
    • Map all related components to their story:
      • Models needed for that story
      • Services needed for that story
      • Endpoints/UI needed for that story
      • If tests requested: Tests specific to that story
    • Mark story dependencies (most stories should be independent)

  2. From Contracts:

    • Map each contract/endpoint → to the user story it serves
    • If tests requested: Each contract → contract test task [P] before implementation in that story's phase

  3. From Data Model:

    • Map each entity to the user story(ies) that need it
    • If entity serves multiple stories: Put in earliest story or Setup phase
    • Relationships → service layer tasks in appropriate story phase

  4. From Setup/Infrastructure:

    • Shared infrastructure → Setup phase (Phase 1)
    • Foundational/blocking tasks → Foundational phase (Phase 2)
    • Story-specific setup → within that story's phase

Phase Structure

  • Phase 1: Setup (project initialization)
  • Phase 2: Foundational (blocking prerequisites - MUST complete before user stories)
  • Phase 3+: User Stories in priority order (P1, P2, P3...)
    • Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
    • Each phase should be a complete, independently testable increment
  • Final Phase: Polish & Cross-Cutting Concerns

Below is a Speckit.analyze file contains that Review tasks for risks, gaps, or missing edge cases before implementation.

---
description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
handoffs: 
  - label: Analyze For Consistency
    agent: speckit.analyze
    prompt: Run a project analysis for consistency
    send: true
  - label: Implement Project
    agent: speckit.implement
    prompt: Start the implementation in phases
    send: true
---

## User Input

```text
$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

  1. Setup: Run .specify/scripts/bash/check-prerequisites.sh --json from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").

  2. Load design documents: Read from FEATURE_DIR:

    • Required: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
    • Optional: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)
    • Note: Not all projects have all documents. Generate tasks based on what's available.

  3. Execute task generation workflow:

    • Load plan.md and extract tech stack, libraries, project structure
    • Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
    • If data-model.md exists: Extract entities and map to user stories
    • If contracts/ exists: Map endpoints to user stories
    • If research.md exists: Extract decisions for setup tasks
    • Generate tasks organized by user story (see Task Generation Rules below)
    • Generate dependency graph showing user story completion order
    • Create parallel execution examples per user story
    • Validate task completeness (each user story has all needed tasks, independently testable)

  4. Generate tasks.md: Use .specify/templates/tasks-template.md as structure, fill with:

    • Correct feature name from plan.md
    • Phase 1: Setup tasks (project initialization)
    • Phase 2: Foundational tasks (blocking prerequisites for all user stories)
    • Phase 3+: One phase per user story (in priority order from spec.md)
    • Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
    • Final Phase: Polish & cross-cutting concerns
    • All tasks must follow the strict checklist format (see Task Generation Rules below)
    • Clear file paths for each task
    • Dependencies section showing story completion order
    • Parallel execution examples per story
    • Implementation strategy section (MVP first, incremental delivery)

  5. Report: Output path to generated tasks.md and summary:

    • Total task count
    • Task count per user story
    • Parallel opportunities identified
    • Independent test criteria for each story
    • Suggested MVP scope (typically just User Story 1)
    • Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)

Context for task generation: $ARGUMENTS

The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.

Task Generation Rules

CRITICAL: Tasks MUST be organized by user story to enable independent implementation and testing.

Tests are OPTIONAL: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.

Checklist Format (REQUIRED)

Every task MUST strictly follow this format:

- [ ] [TaskID] [P?] [Story?] Description with file path

Format Components:

  1. Checkbox: ALWAYS start with - [ ] (markdown checkbox)
  2. Task ID: Sequential number (T001, T002, T003...) in execution order
  3. [P] marker: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
  4. [Story] label: REQUIRED for user story phase tasks only
    • Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
    • Setup phase: NO story label
    • Foundational phase: NO story label
    • User Story phases: MUST have story label
    • Polish phase: NO story label
  5. Description: Clear action with exact file path

Examples:

  • ✅ CORRECT: - [ ] T001 Create project structure per implementation plan
  • ✅ CORRECT: - [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py
  • ✅ CORRECT: - [ ] T012 [P] [US1] Create User model in src/models/user.py
  • ✅ CORRECT: - [ ] T014 [US1] Implement UserService in src/services/user_service.py
  • ❌ WRONG: - [ ] Create User model (missing ID and Story label)
  • ❌ WRONG: T001 [US1] Create model (missing checkbox)
  • ❌ WRONG: - [ ] [US1] Create User model (missing Task ID)
  • ❌ WRONG: - [ ] T001 [US1] Create model (missing file path)

Task Organization

  1. From User Stories (spec.md) - PRIMARY ORGANIZATION:

    • Each user story (P1, P2, P3...) gets its own phase
    • Map all related components to their story:
      • Models needed for that story
      • Services needed for that story
      • Endpoints/UI needed for that story
      • If tests requested: Tests specific to that story
    • Mark story dependencies (most stories should be independent)

  2. From Contracts:

    • Map each contract/endpoint → to the user story it serves
    • If tests requested: Each contract → contract test task [P] before implementation in that story's phase

  3. From Data Model:

    • Map each entity to the user story(ies) that need it
    • If entity serves multiple stories: Put in earliest story or Setup phase
    • Relationships → service layer tasks in appropriate story phase

  4. From Setup/Infrastructure:

    • Shared infrastructure → Setup phase (Phase 1)
    • Foundational/blocking tasks → Foundational phase (Phase 2)
    • Story-specific setup → within that story's phase

Phase Structure

  • Phase 1: Setup (project initialization)
  • Phase 2: Foundational (blocking prerequisites - MUST complete before user stories)
  • Phase 3+: User Stories in priority order (P1, P2, P3...)
    • Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
    • Each phase should be a complete, independently testable increment
  • Final Phase: Polish & Cross-Cutting Concerns

Below is the Speckit.implement file. This file relies on the Speckit.plan.md file to practically implement the feature requested. it execute the task checking off each one.

---
description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
handoffs: 
  - label: Analyze For Consistency
    agent: speckit.analyze
    prompt: Run a project analysis for consistency
    send: true
  - label: Implement Project
    agent: speckit.implement
    prompt: Start the implementation in phases
    send: true
---

## User Input

```text
$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

  1. Setup: Run .specify/scripts/bash/check-prerequisites.sh --json from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").

  2. Load design documents: Read from FEATURE_DIR:

    • Required: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
    • Optional: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)
    • Note: Not all projects have all documents. Generate tasks based on what's available.

  3. Execute task generation workflow:

    • Load plan.md and extract tech stack, libraries, project structure
    • Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
    • If data-model.md exists: Extract entities and map to user stories
    • If contracts/ exists: Map endpoints to user stories
    • If research.md exists: Extract decisions for setup tasks
    • Generate tasks organized by user story (see Task Generation Rules below)
    • Generate dependency graph showing user story completion order
    • Create parallel execution examples per user story
    • Validate task completeness (each user story has all needed tasks, independently testable)

  4. Generate tasks.md: Use .specify/templates/tasks-template.md as structure, fill with:

    • Correct feature name from plan.md
    • Phase 1: Setup tasks (project initialization)
    • Phase 2: Foundational tasks (blocking prerequisites for all user stories)
    • Phase 3+: One phase per user story (in priority order from spec.md)
    • Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
    • Final Phase: Polish & cross-cutting concerns
    • All tasks must follow the strict checklist format (see Task Generation Rules below)
    • Clear file paths for each task
    • Dependencies section showing story completion order
    • Parallel execution examples per story
    • Implementation strategy section (MVP first, incremental delivery)

  5. Report: Output path to generated tasks.md and summary:

    • Total task count
    • Task count per user story
    • Parallel opportunities identified
    • Independent test criteria for each story
    • Suggested MVP scope (typically just User Story 1)
    • Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)

Context for task generation: $ARGUMENTS

The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.

Task Generation Rules

CRITICAL: Tasks MUST be organized by user story to enable independent implementation and testing.

Tests are OPTIONAL: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.

Checklist Format (REQUIRED)

Every task MUST strictly follow this format:

- [ ] [TaskID] [P?] [Story?] Description with file path

Format Components:

  1. Checkbox: ALWAYS start with - [ ] (markdown checkbox)
  2. Task ID: Sequential number (T001, T002, T003...) in execution order
  3. [P] marker: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
  4. [Story] label: REQUIRED for user story phase tasks only
    • Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
    • Setup phase: NO story label
    • Foundational phase: NO story label
    • User Story phases: MUST have story label
    • Polish phase: NO story label
  5. Description: Clear action with exact file path

Examples:

  • ✅ CORRECT: - [ ] T001 Create project structure per implementation plan
  • ✅ CORRECT: - [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py
  • ✅ CORRECT: - [ ] T012 [P] [US1] Create User model in src/models/user.py
  • ✅ CORRECT: - [ ] T014 [US1] Implement UserService in src/services/user_service.py
  • ❌ WRONG: - [ ] Create User model (missing ID and Story label)
  • ❌ WRONG: T001 [US1] Create model (missing checkbox)
  • ❌ WRONG: - [ ] [US1] Create User model (missing Task ID)
  • ❌ WRONG: - [ ] T001 [US1] Create model (missing file path)

Task Organization

  1. From User Stories (spec.md) - PRIMARY ORGANIZATION:

    • Each user story (P1, P2, P3...) gets its own phase
    • Map all related components to their story:
      • Models needed for that story
      • Services needed for that story
      • Endpoints/UI needed for that story
      • If tests requested: Tests specific to that story
    • Mark story dependencies (most stories should be independent)

  2. From Contracts:

    • Map each contract/endpoint → to the user story it serves
    • If tests requested: Each contract → contract test task [P] before implementation in that story's phase

  3. From Data Model:

    • Map each entity to the user story(ies) that need it
    • If entity serves multiple stories: Put in earliest story or Setup phase
    • Relationships → service layer tasks in appropriate story phase

  4. From Setup/Infrastructure:

    • Shared infrastructure → Setup phase (Phase 1)
    • Foundational/blocking tasks → Foundational phase (Phase 2)
    • Story-specific setup → within that story's phase

Phase Structure

  • Phase 1: Setup (project initialization)
  • Phase 2: Foundational (blocking prerequisites - MUST complete before user stories)
  • Phase 3+: User Stories in priority order (P1, P2, P3...)
    • Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
    • Each phase should be a complete, independently testable increment
  • Final Phase: Polish & Cross-Cutting Concerns

For further reading.

[embed]The Agentic SDLC Handbook Pre-release edition. This is a living document - new chapters, case studies, and PROSE refinements ship continuously…danielmeppiel.github.io

[embed]OpenProse - Engineer your agents A programming language for the Intelligent VM. OpenProse brings contracts, composition, and version control to the…openprose.ai

[embed]

[embed]Blog Microsoft's Azure AI ecosystem is huge, and it can be tough to keep track of what's what. This cheat sheet rounds up…eitl.ai

[embed]Spec-driven development with AI: Get started with a new open source toolkit Developers can use their AI tool of choice for spec-driven development with this open source toolkit.github.blog

https://developer.microsoft.com/blog/spec-driven-development-spec-kit

메타데이터
post_id
3615493e1bf4
slug
the-alchemist-codes-no-more-now-he-writes-the-specs-that-makes-the-software-3615493e1bf4
url
https://medium.com/@edbertkwesi.ek/the-alchemist-codes-no-more-now-he-writes-the-specs-that-makes-the-software-3615493e1bf4
canonical_url
https://medium.com/@edbertkwesi.ek/the-alchemist-codes-no-more-now-he-writes-the-specs-that-makes-the-software-3615493e1bf4
author_url
https://medium.com/@edbertkwesi.ek
status
ok
fetched_at
2026-07-17 06:31:53

More on AGT · AI Agents

CH Charles Seidel

How To Properly Use An Epi Pen For Allergic Reactions

Jan 2026· 10,312 claps
MA Marina Wyss

AI Agents: Complete Course

Dec 2025· 6,870 claps $
FA Fatih Nar

The 12-Factor Agent: Why Agentic AI Patterns Look Suspiciously Familiar

Feb 2026· 5,268 claps
MI Michael Lopez Chiesa

Why AI Coding Agents Pass Every Test and Still Get the Physics Wrong

Jun 2026· 4,103 claps
AN Ana Bildea, PhD

How to Use Graphify: Turn Any Folder Into a Knowledge Graph

Apr 2026· 3,087 claps $