Skip to content
FlowForge Logo FlowForge

Tutorial

This tutorial walks through adding a /health endpoint to an existing Node.js service. The goal is not the endpoint itself — it is to experience the full FlowForge loop: session start, Maestro coordination, specialist agents, rule validation, and session end.

Estimated time: 20 minutes.

Prerequisites: A working FlowForge install (see Installation) and a Node.js project with a .flowforge/ directory bootstrapped (see First Session).

Step 1: Start a tracked session

Section titled “Step 1: Start a tracked session”

Open a terminal in your project root and start a session. The timer begins the instant this command returns.

Terminal window
flowforge session:start feature/health-check
Session sess_1745000000000_a1b2c3d4 started on branch "feature/health-check".

Leave this terminal open. The session record lives in .claude/session.json and is visible to Claude Code.

Step 2: Ask the Maestro for options

Section titled “Step 2: Ask the Maestro for options”

Open Claude Code in the same directory and describe the change:

Add a /health endpoint to the API that returns { status: "ok" } and the service uptime in seconds.

Claude Code, acting as the Maestro, does not implement the feature directly. It consults fft-architecture first, which returns three design options:

Option A — Inline handler in app.js
  Pros: minimal diff, zero new files
  Cons: couples health logic to routing, hard to extend


Option B — Dedicated health module (src/health/)
  Pros: clean separation, easy to add dependency checks later
  Cons: one extra file, small up-front cost


Option C — Health library (@org/health) shared across services
  Pros: reusable across the platform
  Cons: overkill for a single service today

The Maestro presents these three options. You choose. No specialist writes code until you approve a path.

Step 3: Implementation by specialists

Section titled “Step 3: Implementation by specialists”

Approve Option B. The Maestro now coordinates a team:

  • fft-backend writes the endpoint and wires it into the router.
  • fft-testing produces unit and integration tests before implementation is finalized (TDD is Rule #3).
  • fft-code-reviewer inspects the diff for quality, style, and rule compliance.

Each agent reports back to the Maestro, which synthesizes the results and surfaces them to you. You approve the final diff before it is committed.

Step 4: Validate rule compliance

Section titled “Step 4: Validate rule compliance”

Before wrapping up, run the full rule audit:

Terminal window
flowforge dev:checkrules
Rule Compliance Check
=====================


[PASS] Project has CLAUDE.md documentation
[PASS] Project has a tests directory
[PASS] Project uses git version control
[PASS] Project has .gitignore for file hygiene
[PASS] Project has a dependency manifest file


Result: 5/5 rules passed.

These five checks cover project-level health. The full FlowForge rule set (35 rules covering TDD, branch policy, commit hygiene, and more) is enforced in real time by pre-tool and post-tool hooks — dev:checkrules confirms the structural prerequisites are in place. If any check fails, the output includes a suggestion for fixing it. Loop back through the Maestro until the audit is clean.

Step 5: End the session

Section titled “Step 5: End the session”

Close the session to finalize the time record and write the summary:

Terminal window
flowforge session:end

The handler returns a single-line success message plus a small structured data object:

message: "Session completed (19m). 2 commit(s), 4 file(s) changed."


data: {
  sessionId: "sess_1745000000000_a1b2c3d4",
  branch: "feature/health-check",
  duration: "19m",
  durationMs: 1140000,
  commits: 2,
  filesChanged: 4
}

The handler writes the completed status, end timestamp, and duration back to .claude/session.json. The file is not deleted — it serves as the record of the most recent session. Starting a new session with session:start will fail until session:end has marked the current one complete.

What just happened

Section titled “What just happened”

This small loop demonstrates the foundations of FlowForge:

  • Time was tracked automatically. No manual timers, no forgotten logs, no guesswork at invoice time.
  • The Maestro coordinated, it did not code. You saw three options, you chose, and specialists executed.
  • Rules ran continuously. Pre-tool hooks blocked unsafe actions in real time; dev:checkrules confirmed the final state.
  • Every decision was auditable. The session record, the git history, and the agent reports together form a complete trail.

Next steps

Section titled “Next steps”