By name: ejs-story-builder description: > Build a complete end-to-end project story from EJS journey and ADR files. Use when: "build story", "generate story", "tell the story", "project narrative", "end-to-end story", "full story", "what happened", "project history", "summarize all sessions". Reads journey sessions and ADRs, synthesizes a chronological narrative covering what was built, how it was built, and collaboration perspectives (human, human+agent, agent, agent-to-agent). Outputs to chat and saves to ejs-docs/narratives/.
EJS Story Builder
Build a complete end-to-end project story from all (or filtered) EJS journey and ADR files. The story covers what was built, how it was built, and weaves in collaboration perspectives: human, human + agent, agent, and agent-to-agent.
Output: The story is displayed in chat AND saved to
ejs-docs/narratives/story-YYYY-MM-DD.md. Always regenerate the full narrative — do not attempt incremental updates to an existing story file.
Steps
0. Identify the Human / Lead Perspective
Before generating the narrative, determine how to identify the primary decision-maker or lead engineer throughout the story. Ask the user:
"How would you like the human/lead perspective to be identified in this narrative?"
Suggested options:
- Personal name: "Alice worked with the Copilot agent..." → Use actual first or full name
- GitHub handle: "@alice-dev identified the gap" → Use GitHub username in bold
- Team name: "The backend team" or "Team Alpha" → For group-led projects
- Role descriptor: "The lead engineer" or "The founder" → Generic but clear
- Generic + Note: "McFuzzySquirrel" with a customization note in the prologue
Default: If the user doesn't specify, check the earliest journey file's author field
and use that name. If no author is populated, use a generic descriptor: "The lead engineer".
Store this identifier as HUMAN_IDENTIFIER and use it throughout the narrative
in place of generic "the human" / "The human's" phrasing.
Optional: If the user provides their own identifier, ask if they want a customization note added to the Prologue explaining that this story template can be adapted by others.
1. Determine Scope
Check if the user specified any filters. If not, include everything.
Supported filters (all optional):
- Date range:
from: YYYY-MM-DDand/orto: YYYY-MM-DD - Tags: match against journey frontmatter
tagsfield - Session IDs: explicit list (e.g.,
ejs-session-2026-04-09-01) - ADR IDs: explicit ADR numbers to anchor the story around (e.g.,
0013, 0016)
If no filters are provided, scope is all journey and ADR files.
2. Gather the Index
Use whichever approach provides the best coverage:
Option A — DB-first (preferred when available):
python3 scripts/adr-db.py story
This returns a high-level narrative index: intent, key decision, key learning, and ADR links per session. Use this as your roadmap, then read full files for detail.
Option B — File-first (fallback):
Scan ejs-docs/journey/ for all ejs-session-*.md files and ejs-docs/adr/
for all numbered ADR files (0010-*.md, 0011-*.md, etc.). Skip the
0000-adr-template.md template and _templates/ directory.
3. Read Source Files
For each session and ADR in scope, read the full markdown file. Extract:
From journey files:
| Section | What to extract |
|---|---|
| YAML frontmatter | session_id, date, agents_involved, tags, adr_links |
| Problem / Intent | The purpose of the session |
| Interaction Summary | The collaboration trail — who said/did what |
| Agent Collaboration Summary | Which agents participated, key suggestions |
| Sub-Agent Contributions | Per-agent: task, decisions, alternatives, outcome, handoffs |
| Agent Influence | Suggestions adopted vs. rejected, human overrides |
| Experiments / Evidence | What was tried, what happened, what changed thinking |
| Iteration Log | Pivots, reversals, refinements |
| Decisions Made | Decision, reason, impact |
| Key Learnings | Technical, prompting, and tooling insights |
| Machine Extracts | INTERACTION_EXTRACT, DECISIONS_EXTRACT, LEARNING_EXTRACT, AGENT_GUIDANCE_EXTRACT, SUB_AGENT_EXTRACT |
From ADR files:
| Section | What to extract |
|---|---|
| YAML frontmatter | adr_id, title, date, status, session_id, actors |
| Context | Problem/opportunity that triggered this |
| Session Intent | What the human intended |
| Collaboration Summary | How human and agent collaborated |
| Considered Options | Options A, B, C with descriptions |
| Decision | The decision made |
| Rationale | Why, trade-offs, rejected alternatives |
| Consequences | Positive and negative |
| Key Learnings | Transferable knowledge |
4. Build Chronological Timeline
- Order all sessions by date (from YAML frontmatter
datefield) - Map ADRs to their originating sessions via
session_id/session_journeycross-references - Group related sessions into narrative arcs:
- Sessions on the same date working toward the same goal → group as one arc
- Sessions across dates on the same feature/theme → group as one arc
- Use Problem/Intent similarity and
tagsoverlap to identify groupings - Solo sessions that stand alone are their own arc
5. Extract Perspectives
As you read each session, tag content by perspective. These perspectives are woven into the chronological narrative — they are NOT separate sections.
| Perspective | Where to find it | What it reveals |
|---|---|---|
| Human | Problem/Intent, human-initiated pivots in Iteration Log, rejected suggestions in Agent Influence | Why this work mattered, what the human prioritized, where the human overrode the agent |
| Human + Agent | Interaction Summary (the back-and-forth), adopted suggestions in Agent Influence, collaborative experiments | How the partnership worked — ideas proposed, refined, accepted |
| Agent | Agent Collaboration Summary, agent-initiated decisions, tool usage, experiment execution | What the agent contributed independently — analysis, code generation, research |
| Agent-to-Agent | Sub-Agent Contributions, handoff chains (SA1→SA2→SA3), inter-agent disagreements | How agents coordinated — delegation, dependency chains, conflict resolution |
6. Generate the Narrative
Write the story using the narrative template as the output structure. Follow these guidelines:
Voice and Style
- Third-person narrative voice — not first-person ("The team..." not "I...")
- Factual and evidence-based — every claim must be traceable to a specific journey session or ADR
- Perspectives woven naturally into the chronological flow:
- "The human set out to solve X. Agent [name] suggested Y, which was adopted because Z."
- "A sub-agent was delegated the research task and surfaced finding W, which shifted the approach."
- "The human rejected the agent's proposal for A, preferring B because..."
- Decisions as story backbone — decisions are the turning points of the narrative, not incidental details
- Pivots as plot points — when direction changed, highlight what triggered the change and the before/after
Narrative Arc Structure
For each arc (grouped sessions), write:
- What was happening — the intent/problem (from Problem/Intent sections)
- How it unfolded — key interactions, experiments, pivots, weaving in all relevant perspectives
- What was decided — decisions with rationale (link to ADR if one was created)
- What was learned — key insights that carried forward
Grouping Rules
- Same-day sessions on related work → combine into one arc with a unifying title
- Multi-day arcs for features that span sessions → group under a theme title
- Standalone sessions → their own arc
- Within each arc, maintain chronological order of individual sessions
- Reference individual session IDs in parentheses so readers can trace back
Connecting the Arcs
- Between arcs, add a brief transition that shows how one arc's outcome led to the next
- Track how decisions compound — show how early decisions constrained or enabled later ones
- Surface recurring themes (e.g., "the simplification pattern appeared again...")
7. Write the Output
- Display the full narrative in chat for the user to review
- Save to file:
ejs-docs/narratives/story-YYYY-MM-DD.md(using today's date)- Create the
ejs-docs/narratives/directory if it doesn't exist
- Create the
- Confirm with a summary:
- Filename and path
- Number of sessions covered
- Number of ADRs referenced
- Date range of the story
- Approximate word count
Contextual References
- Journey template:
ejs-docs/journey/_templates/journey-template.md - ADR template:
ejs-docs/adr/0000-adr-template.md - Database tool:
scripts/adr-db.py(storycommand for index,searchfor queries) - Narrative output template: narrative-template.md
- Session lifecycle patterns:
ejs-docs/session-lifecycle-patterns.md
Key Principle
The story makes the implicit explicit. Every session captured a moment of engineering collaboration. The story connects those moments into a coherent narrative — showing not just what was built, but how humans and agents built it together, what they learned, and where it stands now.