feature-forge

name

feature-forge

description

This skill should be used when the user describes an observation, problem, or feature idea and wants end-to-end design and implementation. Triggers include "I notice...", "feature forge", "design and implement this", "hive-mind PRD", "end-to-end feature", or when the user describes a problem and expects a full product development cycle from PRD through implementation. This skill orchestrates a multi-phase workflow using ruflo hive-mind consensus, beads issue tracking, SPARC planning, and verified implementation.

Feature Forge

Orchestrate end-to-end feature development from observation through PRD consensus, user validation, SPARC planning, and verified implementation.

Requires: ruflo MCP (hive-mind), beads (bd), ralph-loop skill.

Modes

Full Mode (default for large features)

All phases including user persona validation. Use when the feature affects many users, involves subjective trade-offs, is ambiguous, or could be solved multiple ways.

Lite Mode (for small features)

Phases 1 → 2 → 3, skipping Phase 1.5. Use 3 experts (PM, Engineering, Domain) instead of 5. Simpler SPARC. No ralph-loop. Use when the feature is narrow, the solution is obvious, or the user asks to "just build it."

Override with: "go deep on this", "keep it simple", "run user validation", "skip validation".

Autonomy

Runs autonomously by default. Stop only when:

• Genuine ambiguity the hive-mind cannot resolve
• Observation too vague to act on
• Scope dramatically larger than implied
• Design feedback loop triggered (Phase 3 discovers the PRD was wrong)

Stop for review when the user explicitly requests it ("let me review", "review mode", "confirm before implementing").

Workflow

User Observation
       │
       ▼
  Phase 1: Discovery & PRD ◄──────────────────┐
  (Expert Hive-Mind: PM, Design, UX, Eng, Domain)
       │                                        │
       ▼ ── Lite mode skips to Phase 2          │
  Phase 1.5: User Persona Validation            │ Design
  (5 rounds of simulated user research)         │ Feedback
       │                                        │ Loop
       ▼                                        │
  Phase 2: SPARC Planning                       │
  (S-P-A-R-C + beads issues)                    │
       │                                        │
       ▼                                        │
  Phase 3: Implementation & Verification ───────┘
  (build → test → verify → close)               (when implementation
       │                                         reveals design flaw)
       ▼
  Session Close

---

Phase 1: Discovery & PRD

Initialize a mesh hive-mind and spawn 5 experts (3 in Lite mode):

mcp__ruflo__hive-mind_init(queenId: "forge-queen", topology: "mesh")
mcp__ruflo__hive-mind_spawn — forge-pm, forge-design, forge-ux, forge-eng, forge-domain

1. Explore the codebase to understand current state (use Explore agent or direct tools)
2. Store findings in shared memory (hive-mind_memory)
3. Broadcast observation + findings to all experts for analysis
4. Synthesize into a PRD (see references/phase1-discovery.md for template)
5. Consensus via hive-mind_consensus — unanimous approval, max 5 rounds
6. Write approved PRD to docs/prd/<feature-name>.md

See references/expert-personas.md for expert roles and consensus protocol.

Phase transition: Full mode → Phase 1.5. Lite mode → Phase 2.

---

Phase 1.5: User Persona Validation

Iterative design refinement through simulated user research. Also invocable standalone on any existing PRD.

Generate Personas (5-7)

Archetype	Purpose
Power User	Depth, scale, configurability
Newcomer	Discoverability, onboarding, terminology
Skeptic	Adversarial. Actively tries to reject the design. Must find a reason to say no — if they can't, the design might actually be good.
Edge-Case User	Accessibility, i18n, boundary conditions
Reluctant Adopter	Migration path, switching cost
Adjacent Stakeholder	Downstream effects, audit, permissions
Domain Expert	Correctness, standards, professional quality

See references/user-personas.md for persona generation and references/phase1.5-user-validation.md for the full loop.

Validation Rounds (5 iterations)

mcp__ruflo__hive-mind_init(queenId: "forge-users", topology: "mesh")
mcp__ruflo__hive-mind_spawn — one per persona

Each round: Present → React → Synthesize → Decide → Revise → Convergence Check

Exit early if two consecutive rounds produce zero material changes. If round 5 still has changes, flag unresolved tensions.

Write validation report to docs/prd/<feature-name>-validation.md.

---

Phase 2: SPARC Planning

• S - Specification: Problem, success criteria, user stories
• P - Pseudocode: Algorithms, API contracts, data flows (skip in Lite)
• A - Architecture: Files, components, schema, state
• R - Refinement: Edge cases, errors, testing, performance
• C - Completion: Definition of done, task breakdown, acceptance criteria

Evaluate: Usability, Value, Feasibility, Viability.

Write plan to docs/sparc/<feature-name>-implementation.md.

Create Beads

bd create --title="<task>" --type=task --priority=<0-4>
bd dep add <child-id> <parent-id>

See references/phase2-planning.md for details.

---

Phase 3: Implementation & Verification

Implementation Hive

mcp__ruflo__hive-mind_init(queenId: "forge-impl-queen", topology: "hierarchical")
mcp__ruflo__hive-mind_spawn — workers based on scope (1-5)

Implementation Loop

bd ready → bd update <id> --claim → implement → test → verify → bd close <id> → bd ready

Use ralph-loop for complex tasks with testable success criteria (Full mode).

Design Feedback Loop

When implementation reveals the PRD was wrong, do not patch around it:

1. Stop the current implementation bead
2. Document the design flaw: what was assumed, what's actually true, why it matters
3. Update the PRD in docs/prd/<feature-name>.md:
   • Add a ## Design Revisions section (or append to existing)
   • Record: what changed, what triggered it, which phase/bead discovered it
4. Assess cascade: Does this revision invalidate other beads? If yes:
   • Close invalidated beads with bd close <id> --reason="Invalidated by design revision"
   • Create replacement beads reflecting the corrected design
   • Update the SPARC plan
5. Resume implementation with the corrected design

The PRD is a living document, not a historical artifact. It should always reflect the current understanding of the feature.

Triggers for the feedback loop:

• A technical constraint makes a user story impossible as written
• Testing reveals the proposed UX doesn't work in practice
• An edge case invalidates a core assumption in the PRD
• Integration with existing code requires a fundamentally different approach

Final Verification

1. Full test suite passes
2. bd list --status=open shows no feature-related beads open
3. Linters/type checks clean
4. Feature walkthrough (happy path, error paths, edge cases)
5. PRD reflects final implemented state (design feedback loop applied)

See references/phase3-implementation.md for detailed patterns.

---

Session Close

bd sync
git add <changed files>
git commit -m "<descriptive message>"
bd sync
git push

---

Reference Files

File	Phase
references/expert-personas.md	1 — Expert roles, consensus protocol
references/user-personas.md	1.5 — Persona archetypes, adversarial skeptic
references/phase1-discovery.md	1 — PRD template and workflow
references/phase1.5-user-validation.md	1.5 — Validation loop details
references/phase2-planning.md	2 — SPARC plan, beads translation
references/phase3-implementation.md	3 — Impl loop, design feedback, ralph-loop
examples/example-prd.md	— PRD before and after validation
examples/example-sparc.md	— Sample SPARC plan