← All artifacts

PM + Claude Code Workflow

How to organize sessions and artifacts when building features with Claude Code

Session Phases

Each phase has a distinct decision state and produces a specific output type. Start a new session when the phase changes.

Phase Session(s) Input Output Why it's a boundary Model
Understand 1–2 Customer data, existing product, competitive examples Findings document, gap analysis You're learning — output is insight, not decisions Opus — synthesizing patterns across many inputs, surfacing non-obvious connections
Decide 1 Findings + constraints Feature document with decisions Interactive — you're making scope calls in real-time Opus — trade-off analysis, scoping judgment, stakeholder framing
Illustrate 1–2 Decisions from feature doc Prototype(s) on ocean-l.net You're showing, not deciding — iteration is visual Sonnet — following established patterns, building HTML/CSS/JS from decided specs
Specify 1 Feature doc + prototype Stories in Jira You're translating decisions into dev-ready units Opus for complex edge cases; Sonnet for straightforward stories from template
Refine N (short) Dev/QA feedback Updated stories, prototype tweaks Reactive — usually one concern per session Sonnet for prototype polish; Opus if rethinking scope or framing

Key Principles

Finish a phase, save the artifact, then start fresh.
The artifact carries decisions forward — not the conversation history. Memory captures preferences and rules; the feature document captures decisions.
Each session has one primary output type.
When you find yourself saying "now let's switch to..." that's often a session boundary.
The "Decide" session is the most valuable to keep tight.
That's where you're making scope calls with full context of tradeoffs. Don't burn context on research or prototyping in the same session.
"Specify" benefits from a fresh start.
Approach stories with the reader's eyes, not the designer's. If you just spent 3 hours deciding, you'll over-specify.

Anti-patterns

Zigzagging between phases in one session.
Research → decide → prototype → decide more → prototype more → specify → hit context wall. Decisions made early get compressed away by the time you need them.
Continuing a session "just to finish one more thing."
If context has been compacted, earlier decisions are lossy. Start fresh — memory and artifacts carry forward cleanly.

When to Start a New Session

Artifact Organization on ocean-l.net

Each feature gets a subfolder. Within it, artifacts are organized by phase:

Allego/ <feature-name>/ index.html ← landing page with links findings/ ← Understand phase outputs prototypes/ ← Illustrate phase outputs (or flat .html files for simple features) context-package.md ← Attached to epic for Specify phase

For simpler features (like Custom Themes), flat HTML files in the feature folder work fine. Use subfolders when there are many artifacts per phase.

Case Studies

Example: Custom Themes for Lessons

PhaseSession(s)Artifact produced
Understand 1–2 (hit context limits) Theme Color Input — Research Finding.md
Decide 1 (same session, should have been separate) feature-document.md
Illustrate 2–3 (iterations) theme-builder-prototype.html, lesson-theme-admin-prototype.html, theme-reference.html, theme-preview.html
Specify 1 9 Jira stories (ABT-46901–46909), context-package.md
Refine Ongoing Updated stories, prototype fixes, deploy