hoijof-process-v2.md

The Hoijof Process (v2)

The Hoijof Process is a structured, documentation-first, and AI-friendly software development methodology. It is designed to deliver complex projects systematically with high test coverage and transparent decision-making.

This version is specifically tailored for large-context applications, maximizing the efficiency of terminal-based AI assistants (like Claude Code CLI), and preventing the dreaded "AI hallucination loop."

Quick Start (TL;DR)

• Genesis (Phase 0): Bootstrap the Next.js app, configure base-ui, and generate global AI rules (CLAUDE.md).
• Check the Roadmap: Read the current Phase Roadmap (phaseX-roadmap.md) to identify the next priority.
• Design (@Architect): Write the "What" and "Why" (pX-feature-name-design.md) before writing any code. Get user approval.
• Implement (@TDD-Builder): Execute a strict Test-Driven Development loop task-by-task using Vitest/Playwright.
• Context Reset: After a milestone, update the Memory Log, run /clear in the CLI to flush context, and start fresh.
• Phase Close-Out (@Reviewer): Audit the phase, write the final status, update the global ARCHITECTURE.md, and prep the next roadmap.

Folder Structure Overview

File/Folder	Purpose
CLAUDE.md	Global project rules, syntax, and AI instructions.
ARCHITECTURE.md	Living, high-level system architecture document.
/plans/Phase0/	Initialization commands and stack definitions (genesis.md).
/plans/PhaseX/	Contains the Roadmap, Design docs, and TDD execution plans for a specific phase.

Directory Visualization

/
├── CLAUDE.md
├── ARCHITECTURE.md
└── /plans
    ├── /Phase0
    │   └── genesis.md
    └── /Phase1
        ├── phase1-roadmap.md
        ├── phase1-final-status.md
        ├── p1-feature-name-design.md
        └── p1-feature-name.md

0. Phase 0: Genesis & Bootstrapping

Before "Phase 1" begins, the project must be strictly initialized.

• The Blueprint (plans/Phase0/genesis.md): Documents the initial scaffolding commands. For this stack, it includes npx create-next-app@latest, installing @base-ui/react, Tailwind CSS, Vitest, and Playwright.
• AI Rules Initialization: The first action the AI takes is generating a comprehensive CLAUDE.md file. This codifies the Hoijof Process, Next.js App Router conventions, and the exact CLI commands for testing.

1. Phased Master Roadmaps

Work is organized into themed Phases. Each phase relies on a phaseX-roadmap.md following the standard roadmap format below.

Roadmap Format

Every phaseX-roadmap.md MUST follow this structure:

# Phase X — Title & Subtitle
Status: NOT STARTED | IN PROGRESS | COMPLETE

## Current Status (Month Year)
Summary paragraph: what's done, what's in progress, test count, key accomplishments.

## Goal
Concise paragraph describing the phase objectives and focus areas.

## Tasks

### Category Name (e.g., Design System, Registration, Infrastructure)
- [x] PX: Task Title — DONE
- [ ] PX: Task Title
- [ ] PX: Task Title ⟶ POSTPONED to Phase Y

(Group tasks by domain/category, not by abstract priority levels.
Use sequential numbering: P1, P2, P3... within each phase.
Mark completed tasks with [x] and append — DONE.)

### Backlog & Moonshots
- [ ] B1: Future idea not committed to this phase
- [ ] B2: Another future idea

---

## Milestone Details

### PX: Task Title — DONE (or status)
- **Goal**: One-line description of what this achieves.
- Implementation detail bullet points.
- Technical decisions and approach.
- Test count updates (e.g., "39 new tests (1929 total)").
- **Key files**: `path/to/file.ts`, `path/to/component.tsx`
- **Depends on**: Other task IDs or "Nothing"
- **Complexity**: Low | Medium | High | Very High

#### PX Follow-Up Features (Backlog) — optional
- [ ] PX.1: Future enhancement
- [ ] PX.2: Another enhancement

(Repeat for each task. Completed milestones keep their details
as historical reference — never delete them.)

---

## Dependency Graph

(Text-based diagram showing task relationships and parallel tracks.)

     Category A:
                P1 (Task) ── P2 (Task)
                P3 (Task)

     Category B:
                P4 (Task) ── P5 (Task)

**Critical path:** P1 -> P2 (reason)
**Parallel tracks:**
1. **Track Name:** P1, P3
2. **Track Name:** P4 -> P5

---

## Recommended Implementation Order

**Wave 1 — Description:**
P1 (Task), P2 (Task)

**Wave 2 — Description:**
P3 (Task), P4 (Task)

---

## Key Architecture Notes
1. Numbered insights that survive context resets.
2. Important decisions and their rationale.
3. Cross-cutting concerns.

## Memory
- Append-only changelog tracking progress.
- Use absolute dates (e.g., "2026-03-30"), not relative.
- Acts as rolling context summary for the AI after a `/clear`.

Key Format Rules

1. Category grouping over priority tiers: Group tasks by domain (Design System, Infrastructure, Registration) rather than P1/P2 priority levels. This maps to how work actually flows.
2. Milestone Details are mandatory: Every task gets a subsection with Goal, implementation bullets, Key files, Depends on, and Complexity. This is what enables the AI to pick up any task after a context reset.
3. Completed milestones stay: Never delete milestone details after completion. They serve as historical reference and context for future phases.
4. Sequential task numbering: Use P1, P2, P3... within each phase. When renumbering across phases, document the mapping in Memory.
5. Test counts: Track cumulative test counts in milestone details to monitor coverage growth.

2. AI Personas & Feature Design

To prevent the AI from confusing planning with execution, we invoke specific "Personas."

@Architect Mode (Design Document)

Before writing code, the AI creates pX-feature-name-design.md.

• Focus: The "What" and the "Why."
• Content: Data Models, API contracts, and Testing Strategy.
• Constraint: The Architect is forbidden from writing implementation code.
• Approval: Must receive a Status: APPROVED from the user to proceed.

3. Strict TDD Implementation & Resilience

Once approved, the AI switches to the @TDD-Builder persona using the pX-feature-name.md execution plan.

• Step 1: Write failing tests (Red).
• Step 2: Verify failure via terminal output.
• Step 3: Write implementation code (Green).
• Step 4: Verify success via tests.
• Step 5: Atomic Commit (e.g., git commit -m "feat(p1): add auth toast").

Important

AI Resilience: The "Stuck Loop" Circuit Breaker

• The Rule of 3: If a test fails 3 consecutive times, the AI must STOP writing code.
• The Fallback: The AI must write a temporary DEBUG.md analyzing the logs and ask the user for architectural clarification.

4. Phase Close-Out & Global Architecture

When milestones are complete, the AI becomes the @Reviewer:

• Audit: Check for technical debt and edge-case coverage.
• Final Status: Write plans/PhaseX/phaseX-final-status.md.
• Global Update: Distill changes into the root ARCHITECTURE.md. This ensures that in Phase 10, the AI understands the core data flow built in Phase 1.

5. Claude Code CLI Workflows

• Context Priming: The hierarchy of ARCHITECTURE.md → Roadmaps → Design Docs creates a perfect "mental map" for the AI, eliminating hallucinations.
• Context Reset Protocol: As the session fills up, summarize the progress in the Memory Log, run /clear to wipe history, and re-prime by reading the roadmap and the next plan.