Flow Journey Author

flow-journey-author

Per-domain journey doc authoring sub-skill. Writes ONE markdown file per domain conforming to the Q26 locked journey-doc template. Single Agent(journey-doc-author) per domain --- multi-agent staged authoring is parked for v1.1 if domain content bloats past context limits.

This skill is NOT user-invocable (disable-model-invocation: true, per Q7).

Ordering constraint. Runs AFTER flow-doc-author (Q15). Even greenfield NOT_STARTED stubs confirm flow IDs + personas + related_flows for journey authoring. Uniform ordering simplifies the orchestrator --- the ~60s parallelism savings on greenfield doesn't justify conditional ordering against ~5min/gate human review time on retrofit.

The full design rationale lives in docs/design-rationale/fda-plugin-interview.md Q16 (memory:126-145). Q26 defines the journey-doc template; Q15 (memory:108-124) defines the upstream story-doc author this skill reads from.

1. Authoring strategy (Q16.1) --- hybrid

Deterministic stamping --- the build_journey_frontmatter.py builder (BC-13028, ADR-033)

The frontmatter is stamped by an extracted deterministic builder, not LLM prose, so it is fixture-lockable and cannot silently regress to empty placeholders (the journey half of BC-13028 #4; the story half is build_story_frontmatter.py per BC-13168 — a deliberately SEPARATE script, since the two share no parsing core). The skill shells out to scripts/build_journey_frontmatter.py, which reads exactly two standardized inputs — the per-domain scaffold-log's frontmatter (templates/.flow/scaffold-log/SCHEMA.md; the body tables are never parsed) and the domain's story-doc frontmatter (deterministically stamped since BC-13168) — and emits the ADR-033 canonical 9-key block:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/build_journey_frontmatter.py \
  --scaffold-log <repo>/.flow/scaffold-log/<domain>.md \
  --flows-dir <repo>/docs/product/flows/<domain> --as-of <today>

Degrade contract: junk/missing scaffold-log values → TBD (never malformed YAML); a YAML-unsafe milestone name is emitted double-quoted; story docs without a valid flow_id are skipped whole; zero valid story docs → exit 2 (the Q16.8 ordering contract was violated — fail loud, never stamp honest-empties). The lock is tests/run-journey-frontmatter-vslice.sh (golden + populated-key assertions). Schema canon: docs/decisions/033-fda-journey-frontmatter-canon.md.

The H1 title (# <DOMAIN>: <Display name>) and doc-type blockquote are body items authored by the agent (body-only contract below).

Agent-authored sections (body-only contract)

Single Agent(journey-doc-author) call authors the body only --- the H1 title # <DOMAIN>: <Display name>, the doc-type blockquote, and 7-9 narrative sections --- and returns it as markdown. The skill prepends the builder-stamped frontmatter and writes the file. The agent never emits frontmatter: it is filesystem-only, so it cannot know the milestone UUID --- that contradiction was the proximate cause of the placeholder frontmatter (BC-13028 #4). Sections:

• 7 always-required:
  1. ## Actor / Persona
  2. ## Scenario + Expectations
  3. ## Journey phases --- with N variable sub-phases
  4. ## Out of scope
  5. ## Related domains and cross-scenario journeys
  6. ## Open questions
  7. ## See also
• 1 sometimes-included: ## Decision points (skip if linear journey).
• 1 optional: ## L2 review summary (Q26 mod 2) --- populated only if L2 review ran for this domain per the meta-Q lock; captures CEO + Design perspectives.

Per-phase structure

Each ## Phase N entry contains:

• *Persona:* line
• *Mindset:* line
• 2-paragraph narrative
• **Pain points:** bullets
• **Opportunities:** bullets
• Job stories table referencing real flow IDs

Single agent (not multi-agent staged) is the locked dispatch mode --- preserves cross-phase narrative continuity. Multi-agent staged authoring is parked v1.1 if a domain bloats past the agent's context limit.

2. Dispatch pattern (Q16.2) --- 1 agent per domain; parallel across domains

The agent runs in parallel across domains within a concurrency cap of ~10 (avoids Claude Code background-agent queueing), NOT in parallel within a domain (which would break cross-phase narrative continuity).

3. Idempotency (Q16.3) --- skip-if-exists + --force

Same as Q15.3. Pre-write check per docs/product/journeys/<domain>.md:

• Default: skip + summarize at end-of-run.
• --force: overwrite.
• Interactive mode: per-doc AskUserQuestion.

4. Fidelity-review (Q16.4) --- 2-layer

Mechanical layer

bash scripts/verify-docs.sh once after the batch (same as Q15.4).

Narrative layer

Per-doc background fidelity-review. Journey-specific drift checks added to the reviewer prompt:

• Phase count > 0.
• Each phase has the required sub-structure: persona + mindset + narrative + pain points + opportunities + job stories table.
• Job stories table references real flow IDs (no fabricated rows).
• Status values match the canonical taxonomy.
• Cross-scenario journey references resolve OR are explicitly TBD.

5. Failure recovery (Q16.5) --- log + continue

Same as Q15.5. Domain-failed-doc surfaces in the end-of-run summary; user re-runs the skill with --force (idempotent against the failure list).

6. User-confirmation gates (Q16.6) --- 0 synchronous gates

Filesystem write; git review is the implicit gate. Contributes 0 to Q10's 5/4 budget. Same rule as Q15.6.

7. Authoring context (Q16.7)

The per-domain agent prompt receives:

• Q26 template path.
• Inventory section block for the domain.
• All N story docs at docs/product/flows/<domain>/*.md (authored by flow-doc-author in the prior step).
• Persona doc(s) for in-scope personas.
• PROJECT-INTENT.md.
• Linear milestone description from scaffold output.
• Optional L2 review summary if state.l2_review_<domain> exists in the orchestrator's state object.

Story-docs-as-context is what makes the journey synthesize across flows. TEAM cut-1a -> cut-1b precedent --- the journey doc is a narrative consolidation, not an independent draft.

8. Ordering constraint (Q16.8)

Serial within a domain: flow-linear-scaffold -> flow-doc-author -> flow-journey-author. NOT in parallel.

Cross-domain: parallel (Section 2).

Even greenfield NOT_STARTED stubs confirm flow IDs + personas + related_flows for the journey author. Uniform ordering simplifies the orchestrator.

L-review summary routing (clarified at Q16 lock time)

Worked example

/flow:start-project greenfield, 5 domains:

1. Skill reads state.scaffold_log for all 5 domains -> 5 milestone UUIDs + N parent BCs + 5N children BCs.
2. Skill reads docs/product/flows/<domain>/*.md for all 5 domains -> ~31 story docs total (authored by Q15).
3. Skill stamps 5 frontmatter blocks via build_journey_frontmatter.py (scaffold-log frontmatter + story-doc aggregation, Section 1), then fans out 5 background body-only agents in parallel (all 5 fit in 1 batch under the ~10 concurrency cap per Section 2) and prepends each stamped block to its returned body at collection.
4. ~60-90s wall time (5 domains in a single batch; matches the per-domain footprint anchor — ceil(5/10) * ~90s = ~90s).
5. Mechanical layer: bash scripts/verify-docs.sh logs 0 errors.
6. Narrative layer: 5 fidelity-review agents; 4 PASS, 1 flagged for missing ## Open questions section.
7. End-of-run summary: flow-journey-author: 5/5 journeys authored, 1 narrative-drift flagged (tenancy missing Open questions).

See also

• docs/design-rationale/fda-plugin-interview.md Q16 --- canonical 8-sub-decision spec.
• docs/design-rationale/fda-plugin-interview.md Q26 --- journey-doc template.
• docs/design-rationale/fda-plugin-interview.md Q15 --- upstream story-doc author.
• skills/flow-doc-author/SKILL.md --- preceding sub-skill (provides story docs as authoring context).
• skills/flow-linear-scaffold/SKILL.md --- preceding sub-skill (writes the scaffold-log whose frontmatter sources the linear_milestone field).
• skills/flow-regen-index/SKILL.md --- downstream sub-skill (consumes the journey doc's linear_milestone.id for the INDEX header milestone link, per ADR-033).
• docs/decisions/033-fda-journey-frontmatter-canon.md (repo root) --- the journey frontmatter schema canon this skill stamps.