fullstack-feature

Resources

scripts/
  validate-feature-workflow.sh
references/
  phase-templates.md

Fullstack Feature Orchestration

This skill defines the end-to-end workflow for implementing complete features that span multiple layers of the stack. It orchestrates specialized agents through 7 distinct phases, from requirements clarification through delivery.

When to Use This Skill

Use fullstack-feature when the user requests:

• A complete feature that requires database, API, and UI changes
• End-to-end implementation with testing and review
• A new user-facing capability that touches multiple components
• Anything described as: "build X", "add X feature", "implement X capability"

Do NOT use this skill for:

• Single-layer changes (just API, just UI)
• Bug fixes (use bugfix or hotfix skills)
• Code review only (use review-scoring skill)
• Refactoring without new functionality

Overview

The fullstack feature workflow consists of 7 phases:

1. Understand - Clarify requirements, load skills, identify affected layers
2. Foundation (sequential) - Database schema/migrations, type generation
3. Core Implementation (parallel) - API endpoints, UI components, state management
4. Integration (sequential) - Wire UI to API, state to UI, verify data flow
5. Quality (parallel) - Tests, security check, accessibility check
6. Review (runtime-driven) - WRFC chains from prior phases complete via runtime <gv> directives
7. Commit + Log - Triggered when runtime issues complete directives; git commit, update memory/logs, report to user

Runtime Engine and WRFC Chains

The runtime engine automatically creates a WRFC (Work-Review-Fix-Complete) chain for each work agent. When an agent completes its work and emits a <gv> tag, the runtime:

1. Evaluates the output against the configured score_threshold (default: 9.5 from goodvibes.json)
2. Issues directives to the orchestrator via system messages
3. Orchestrator executes those directives mechanically

Directive types:

{"action":"spawn","wid":"wrfc_xxx","type":"reviewer","task":"Review the code..."}
{"action":"spawn","wid":"wrfc_xxx","type":"engineer","task":"Fix the issues..."}
{"action":"complete","wid":"wrfc_xxx"}
{"action":"escalate","wid":"wrfc_xxx","reason":"Max fix attempts reached"}

Directive compliance rules (absolute):

1. Immediate: Execute directives the moment they arrive. NEVER defer, queue, or delay.
2. First: Execute directives BEFORE any other action. No intervening tool calls, no additional agent spawns, no user messages first.
3. Autonomy ends: Once the first directive arrives for a WRFC chain, the orchestrator has no further judgment over that chain. Only directives drive it.
4. Runtime supersedes: Runtime workflow logic ALWAYS supersedes orchestrator judgment. If a directive says review, review. If it says complete, complete.

The orchestrator does NOT manually spawn reviewers or fix agents. These come exclusively from runtime directives.

Phase 1: Understand

Purpose

Ensure you have complete clarity on what to build before spawning work agents. This phase prevents wasted effort from misunderstandings.

Steps

1. Clarify requirements with the user:

   • What is the exact functionality requested?
   • Who are the users and what are their goals?
   • What are the acceptance criteria (how do we know it's done)?
   • Are there specific constraints (performance, accessibility, browser support)?
   • Are there existing patterns to follow or avoid?

2. Identify affected layers:

   • Database: New tables/columns? Migrations?
   • API: New endpoints? Modify existing?
   • Types: New type definitions?
   • UI: New components? Modify existing?
   • State: New state management?
   • Tests: Unit, integration, e2e?

3. Load relevant outcome skills:

   • Backend: trpc, prisma, postgresql, clerk, nextauth, graphql, rest-api-design
   • Frontend: nextjs, react, tailwindcss, shadcn-ui, framer-motion
   • Protocol: gather-plan-apply, review-scoring, goodvibes-memory

4. Check goodvibes memory:

   • .goodvibes/memory/decisions.json - Architectural choices
   • .goodvibes/memory/patterns.json - Coding patterns
   • .goodvibes/memory/failures.json - Past failures to avoid

5. Create implementation plan:

   • Decompose feature into sub-tasks
   • Identify dependencies between sub-tasks
   • Estimate scope (how many files/components)
   • Map sub-tasks to phases (Foundation, Core, Integration)

Output

At the end of Phase 1, you must have:

• Requirements document (in memory/current-task.md)
• Affected layers list (database, API, UI, tests)
• Implementation plan (decomposed sub-tasks with dependencies)
• Loaded skills (relevant outcome skills available)

Mode-Specific Behavior

Vibecoding: Confirm with user before proceeding to Phase 2. Justvibes: Auto-proceed if requirements are clear. (Pause for clarification if ambiguous.)

Phase 2: Foundation (Sequential)

Purpose

Establish the data model and type foundation before building any upstream code. This ensures type safety and consistency across layers.

Steps

1. Database schema (if required):

   • Spawn database agent to design schema
   • Create migration files
   • Run migrations (dev environment)
   • Verify migration success

2. Type generation (if using Prisma/Drizzle/etc):

   • Run ORM type generation command
   • Verify types are generated
   • Commit generated types (if necessary)

3. Shared type definitions (if not using ORM):

   • Create src/types/[...].ts files
   • Define entities, DTOs, request/response types
   • Export from barrel index.ts

Agent Instructions

Database agent:

Protocol skills (required for all agents): gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory

• Use gather-plan-apply protocol
• Follow existing schema patterns (check memory/decisions.json)
• Add appropriate indexes for query performance
• Add foreign key constraints
• Use timestamps (createdAt, updatedAt)
• Test migration before completing

Engineer agent (type generation):

Protocol skills (required for all agents): gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory

• Run type generation command
• Verify types are correct (spot check generated code)
• Run tsc to confirm no type errors

Clear Definition of Done

• Database schema exists, migrations applied
• Types generated and exported
• npm run typecheck passes
• All files committed

Mode-Specific Behavior

Vibecoding: Checkpoint after this phase. Commit with message checkpoint: foundation - schema and types. Justvibes: Auto-proceed to Phase 3.

Phase 3: Core Implementation (Parallel)

Purpose

Implement the main functionality across API and UI layers in parallel. This maximizes throughput and minimizes wait time.

Sub-Phases

These sub-phases run in parallel:

1. API endpoints (API agent)
2. UI components (UI agent)
3. State management (State agent)

Agent Instructions

API agent:

Protocol skills (required for all agents): gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory

• Implement endpoints using existing patterns (check decisions.json for API style)
• Add input validation (use Zod or similar)
• Add error handling
• Add authentication/authorization checks
• Use ORM for database access
• Add logging at appropriate levels
• Use gather-plan-apply protocol

UI agent:

Protocol skills (required for all agents): gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory

• Create components using existing patterns (check decisions.json for UI libraries)
• Follow accessibility best practices (ARIA attributes, keyboard navigation)
• Implement responsive design
• Add loading and error states
• Optimize performance (useMemo, useCallback)
• Use gather-plan-apply protocol

State agent:

Protocol skills (required for all agents): gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory

• Implement state management using existing patterns (Zustand, Redux, etc)
• Define state shape and actions
• Add selectors for derived state
• Add persistence if required (localStorage, sessionStorage)
• Use gather-plan-apply protocol

Clear Definition of Done

• All API endpoints implemented and validated
• All UI components created
• State management implemented
• npm run typecheck passes
• npm run lint passes
• All files committed

Mode-Specific Behavior

Vibecoding: Checkpoint after this phase. Commit with message checkpoint: core implementation. Justvibes: Auto-proceed to Phase 4.

Phase 4: Integration (Sequential)

Purpose

Connect UI to API, wire state to UI, and verify data flows end-to-end. This phase must be sequential because it depends on Phase 3 completion.

Steps

1. Wire UI to API:

   • Add API client calls to components
   • Handle loading states during API calls
   • Handle error states from API
   • Display API responses in UI

2. Wire state to UI:

   • Connect state management to components
   • Use selectors to access state
   • Dispatch actions on user interactions
   • Verify UI updates when state changes

3. End-to-end verification:

   • Manually test data flow: UI -> API -> Database -> API -> UI
   • Confirm loading states appear
   • Confirm error states appear on failure
   • Confirm success states appear on success

4. Fix integration issues:

   • Fix type mismatches between UI and API
   • Fix data mapping issues
   • Fix state synchronization issues

Agent Instructions

Integration agent:

Protocol skills (required for all agents): gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory

• Read both API and UI code to understand interfaces
• Add API client calls in correct lifecycle hooks (useEffect, event handlers)
• Ensure error handling is present
• Ensure loading states are displayed
• Test each integration point manually
• Use gather-plan-apply protocol

Clear Definition of Done

• UI components can call API endpoints
• Data flows from UI -> API -> DB -> API -> UI
• State works correctly
• Loading states display
• Error states display
• npm run typecheck passes
• All files committed

Mode-Specific Behavior

Vibecoding: Checkpoint after this phase. Commit with message checkpoint: integration. Justvibes: Auto-proceed to Phase 5.

Phase 5: Quality (Parallel)

Purpose

Verify the implementation meets quality standards across multiple dimensions. These checks run in parallel. Each spawned agent will have its own WRFC chain managed by the runtime engine.

Sub-Phases

These sub-phases run in parallel:

1. Tests (Tester agent)
2. Security check (Security agent)
3. Accessibility check (A11y agent)

Agent Instructions

Tester agent:

Protocol skills (required for all agents): gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory

• Write unit tests for API endpoints
• Write component tests for UI
• Write integration tests for data flow
• Target >=80% coverage for new code
• Test both happy path and edge cases
• Use gather-plan-apply protocol

Security agent:

Protocol skills (required for all agents): gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory

• Check for input validation on all endpoints
• Check for authentication/authorization checks
• Check for SQL injection vulnerabilities
• Check for XSS vulnerabilities
• Check for exposed secrets
• Check for CORS configuration
• Use gather-plan-apply protocol

A11y agent:

Protocol skills (required for all agents): gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory

• Check for ARIA attributes on interactive elements
• Check for keyboard navigation support
• Check for color contrast (WCAG AA)
• Check for focus indicators
• Check for alt text on images
• Use gather-plan-apply protocol

Clear Definition of Done

• Tests written and passing
• Security check complete (no critical issues)
• Accessibility check complete (no critical issues)
• All files committed

Mode-Specific Behavior

Vibecoding: Checkpoint after this phase. Commit with message checkpoint: quality checks. Justvibes: Auto-proceed; runtime handles review cycles.

Phase 6: Review (Runtime-Driven)

Purpose

Ensure all code meets production standards through systematic review and fix. The runtime engine manages this phase automatically via <gv> directives.

How It Works

The orchestrator does NOT manually spawn reviewers. Instead:

1. Each work agent from Phases 2-5 completes and emits a <gv> tag
2. The runtime engine evaluates the output and issues directives:
   • If review is needed: {"action":"spawn","type":"reviewer","task":"..."}
   • If fixes are needed after review: {"action":"spawn","type":"engineer","task":"Fix: ..."}
   • If the score meets score_threshold (configured in goodvibes.json): {"action":"complete"}
   • If max_fix_attempts is exhausted: {"action":"escalate","reason":"..."}
3. The orchestrator executes each directive immediately and mechanically

Orchestrator Behavior

• On spawn directive: spawn the specified agent with the provided task prompt
• On complete directive: mark the chain done, proceed to Phase 7 when all chains complete
• On escalate directive: report to user with the escalation reason; do not attempt to fix the chain manually

Clear Definition of Done

• All WRFC chains have received complete directives from the runtime
• No chains are pending escalation resolution

Mode-Specific Behavior

Both vibecoding and justvibes modes follow directives identically. The runtime engine determines when review cycles end. The orchestrator has no mode-specific behavior in this phase beyond executing directives.

Phase 7: Commit + Log

Purpose

Finalize the feature by committing to git and updating project memory. This phase is triggered when the runtime issues complete directives for all WRFC chains from Phases 2-5.

Steps

1. Create git commit:

   • Stage all new/modified files
   • Write clear commit message (follow existing conventions)
   • Include Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
   • Commit

2. Update goodvibes memory:

   • Add to .goodvibes/memory/patterns.json (if new patterns emerged)
   • Add to .goodvibes/memory/decisions.json (if new decisions made)
   • Use goodvibes-memory skill

3. Update goodvibes logs:

   • Log feature completion to .goodvibes/logs/tasks.jsonl
   • Include feature name, files changed, final score
   • Use goodvibes-memory skill

4. Report to user:

   • Summarize what was built
   • List files created/modified
   • List commit SHA
   • Provide next steps (if any)

Clear Definition of Done

• All files committed to git
• Memory updated
• Logs updated
• User report provided

Mode-Specific Behavior

Vibecoding: Confirm commit message with user before committing. Justvibes: Auto-commit with generated message.

Mode-Specific Behavior

Vibecoding Mode

Vibecoding mode is collaborative. The orchestrator:

• Confirms after Phase 1 (Understand) before proceeding
• Checkpoints after Phases 2, 3, 4, 5 (creates git commits)
• Confirms commit message before final commit in Phase 7
• Pauses for approval if uncertainties arise

Once agents are spawned, the runtime engine drives WRFC chains automatically. The orchestrator executes directives mechanically regardless of mode.

Checkpoint commit messages:

• checkpoint: foundation - schema and types
• checkpoint: core implementation
• checkpoint: integration
• checkpoint: quality checks

Justvibes Mode

Justvibes mode is autonomous. The orchestrator:

• Auto-proceeds through all phases without user input
• Pauses only if requirements are ambiguous or critical decisions are needed
• Auto-commits in Phase 7 (generates commit message)

The runtime engine manages all WRFC cycles in both modes identically.

Agent Orchestration Patterns

Sequential Phases

Phases 2, 4, 7 must be sequential:

• Phase 2 (Foundation): Must complete before Phase 3 because API/UI code depends on types
• Phase 4 (Integration): Must come after Phase 3 because it connects API+UI
• Phase 7 (Commit+Log): Must be last; triggered by complete directives for all chains

Parallel Phases

Phases 3 and 5 spawn multiple agents in parallel:

• Phase 3 (Core): API agent, UI agent, State agent run in parallel
• Phase 5 (Quality): Tester agent, Security agent, A11y agent run in parallel

All agents in a parallel phase must receive complete directives before proceeding to the next phase.

Agent Communication

Agents should NOT communicate directly. Instead:

• Agents write results to filesystem
• Orchestrator reads agent outputs
• Orchestrator passes relevant info to next agents

Integration with Other Protocols

Gather-Plan-Apply (GPA)

All work agents must follow the GPA loop:

1. Discover: Use discover tool to run parallel grep/glob/symbol queries
2. Plan: Identify files to create/modify, order of operations, batch opportunities
3. Batch: Group operations into batched precision_engine calls
4. Loop: Return to discovery if assumptions change

See gather-plan-apply skill for details.

Review-Scoring (WRFC)

The runtime engine uses the review-scoring rubric internally when spawning reviewers. The orchestrator does not score code directly. Review thresholds are configured in goodvibes.json (score_threshold, max_fix_attempts).

See review-scoring skill for details on what the reviewer agent does.

Goodvibes Memory

Use goodvibes-memory skill to:

• Read .goodvibes/memory/{decisions,patterns,failures}.json in Phase 1
• Write to .goodvibes/logs/tasks.jsonl in Phase 7
• Update memory files with new patterns/decisions in Phase 7

Common Pitfalls

Starting Implementation Too Early

Do not spawn work agents until Phase 1 is complete. Clarify requirements first.

Parallelizing Sequential Phases

Do not run Phases 2 and 3 in parallel. Phase 3 depends on Phase 2 types.

Skipping Quality Phase

Do not skip Phase 5. Tests are not optional. Security is not optional.

Manually Scheduling Reviewers

Do not add reviewer tasks to Phase 6 manually. The runtime engine issues reviewer spawn directives automatically when each work agent completes. Manual scheduling bypasses the runtime's threshold enforcement.

Deferring Directives

Do not defer, reorder, or skip <gv> directives. Execute them immediately as the first action when received.

Committing Without All Chains Complete

Do not commit in Phase 7 until all WRFC chains have received complete directives. Partial completions are not done.

Forgetting to Update Memory

Do not skip memory updates in Phase 7. Future agents rely on this context.

Validation

Use scripts/validate-feature-workflow.sh to verify your orchestration follows this workflow. See references/phase-templates.md for detailed templates and examples.