Skip to content

Latest commit

 

History

History
389 lines (273 loc) · 11.6 KB

SESSION-GUIDES.md

File metadata and controls

389 lines (273 loc) · 11.6 KB

Session Workflow Guides

Quick reference for each session type. For concepts (FSM, two-tier architecture), see METHODOLOGY.md.

Session Decision Tree

Starting from pattern brief?
├── Yes → Need code stubs now? → Yes → Planning + Design
│                              → No  → Planning
└── No  → Ready to code? → Yes → Complex decisions? → Yes → Design first
                                                    → No  → Implementation
                        → No  → Planning
Session Input Output FSM Change
Planning Pattern brief Roadmap spec (.feature) Creates roadmap
Design Complex requirement Decision specs + code stubs None
Implementation Roadmap spec Code + tests roadmap→active→completed
Planning + Design Pattern brief Spec + stubs Creates roadmap

Planning Session

Goal: Create a roadmap spec. Do not write implementation code.

Context Gathering

pnpm process:query -- overview                                # Project health
pnpm process:query -- list --status roadmap --names-only      # Available patterns

Checklist

  • Extract metadata from pattern brief:

    • Phase number → @<prefix>-phase
    • Dependencies → @<prefix>-depends-on
    • Status → @<prefix>-status:roadmap (always roadmap)

  • Create spec file at {specs-directory}/{product-area}/{pattern}.feature

  • Structure the feature:

    @<prefix>
@<prefix>-pattern:MyPattern
@<prefix>-status:roadmap
@<prefix>-phase:15
Feature: My Pattern

  **Problem:** One sentence.

  **Solution:**
  - Key mechanism 1
  - Key mechanism 2

  • Add deliverables table:

    Background: Deliverables
  Given the following deliverables:
    | Deliverable | Status  | Location | Tests | Test Type |
    | Core types  | pending | src/types.ts | Yes | unit |

  • Convert tables to Rules — Each business constraint becomes a Rule: block

  • Add scenarios per Rule — Minimum: 1 @happy-path + 1 @validation

  • Set executable specs location:

    @<prefix>-executable-specs:{package}/tests/features/behavior/{pattern}

Do NOT

  • Create .ts implementation files
  • Transition to active
  • Ask "Ready to implement?"

Example: delivery-process dogfood

See tests/features/validation/fsm-validator.feature for a complete roadmap spec with Rules, ScenarioOutlines, and proper tagging.

Design Session

Goal: Make architectural decisions. Create code stubs with interfaces. Do not implement.

Context Gathering

pnpm process:query -- context <PatternName> --session design  # Full context bundle
pnpm process:query -- dep-tree <PatternName>                  # Dependency chain
pnpm process:query -- stubs <PatternName>                     # Existing design stubs

Use these before launching explore agents. See PROCESS-API.md.

When Required

Use Design Session Skip Design Session
Multiple valid approaches Single obvious path
New patterns/capabilities Bug fix
Cross-context coordination Clear requirements

Checklist

  • Record decisions as PDR .feature files in delivery-process/decisions/

  • Document options — At least 2-3 approaches with pros/cons

  • Get approval — User must approve recommended approach

  • Create code stubs in delivery-process/stubs/{pattern-name}/:

    // delivery-process/stubs/{pattern-name}/my-function.ts
/**
 * @<prefix>
 * @<prefix>-status roadmap
 * @<prefix>-implements MyPattern
 * @<prefix>-uses Workpool, EventStore
 *
 * ## My Pattern - Description
 *
 * Target: src/path/to/final/location.ts
 * See: PDR-001 (Design Decision)
 * Since: DS-1
 */
export interface MyResult {
  id: string;
}

export function myFunction(args: MyArgs): Promise<MyResult> {
  throw new Error('MyPattern not yet implemented - roadmap pattern');
}

    Stubs live outside src/ to avoid TypeScript compilation and ESLint issues. They are scanned by the documentation pipeline via -i 'delivery-process/stubs/**/*.ts'.

  • Verify stub identifier spelling — Check all exported function/type/interface names for typos before committing stubs

  • List canonical helpers in @<prefix>-uses — If the function does status matching, reference isDeliverableStatusComplete/isDeliverableStatusPending from taxonomy/deliverable-status.ts

Do NOT

  • Create markdown design documents (use decision specs instead)
  • Create implementation plans
  • Transition spec to active
  • Write full implementations (stubs only)

Implementation Session

Goal: Write code. The roadmap spec is the source of truth.

Context Gathering (Step 0)

# Pre-flight — catches FSM violations, missing deps, incomplete deliverables
pnpm process:query -- scope-validate <PatternName> implement

# Curated context — deliverables, FSM state, test files
pnpm process:query -- context <PatternName> --session implement

# File paths for implementation
pnpm process:query -- files <PatternName> --related

The scope-validate command replaces the manual pre-flight checklist — it checks dependency completion, deliverable definitions, FSM validity, and design decisions. See PROCESS-API.md.

Execution Checklist

  1. Transition to active FIRST (before any code):

    # Change in roadmap spec:
@<prefix>-status:active

    Protection: active = scope-locked (no new deliverables)

  2. Create executable spec stubs (if @<prefix>-executable-specs present):

    @<prefix>-implements:MyPattern
Feature: My Pattern Behavior

  3. For each deliverable:

    • Read acceptance criteria from spec
    • Implement code (replace throw new Error)
    • Preserve @<prefix>-* annotations in JSDoc
    • Write tests
    • Update deliverable status: 
      | Core types | complete | src/types.ts | Yes | unit |

  4. Verify all design decisions addressed:

    • Run pnpm process:query -- decisions <SpecName> and confirm each DD-N has a corresponding // DD-N: comment in the implementation

  5. Transition to completed (only when ALL done):

    @<prefix>-status:completed

    Protection: completed = hard-locked (requires @<prefix>-unlock-reason to modify)

  6. Regenerate docs:

    pnpm docs:all

Do NOT

  • Add new deliverables to an active spec
  • Mark completed with incomplete work
  • Skip FSM transitions
  • Edit generated docs directly

Planning + Design Session

Goal: Create spec AND code stubs in one session. For immediate implementation handoff.

When to Use

Use Planning + Design Use Planning Only
Need stubs for implementation Only enhancing spec
Preparing for immediate handoff Still exploring requirements
Want complete two-tier architecture Don't need Tier 2 yet

Checklist

  1. Complete Planning checklist (above)

  2. Add @<prefix>-executable-specs tag pointing to Tier 2 location

  3. Create code stubs (see Design Session checklist)

  4. Create Tier 2 directory:

    {package}/tests/features/behavior/{pattern-name}/

  5. Create Tier 2 feature stubs:

    @<prefix>-implements:MyPattern
@acceptance-criteria
Feature: My Pattern - Rule Name

  @happy-path
  Scenario: Happy path from roadmap spec
    # Implementation placeholder
    Given {precondition}
    When {action}
    Then {outcome}

  6. Create step definitions stub at tests/planning-stubs/{pattern}.steps.ts:

    /**
 * @<prefix>-implements:MyPattern
 *
 * NOTE: In tests/planning-stubs/ (excluded from test runner).
 * Move to tests/steps/ during implementation.
 */

interface TestState {
  result: unknown;
  error: Error | null;
}

let state: TestState;
// Steps with: throw new Error("Not implemented: description");

Handoff Complete When

Tier 1:

  • All @<prefix>-* tags present
  • @<prefix>-executable-specs points to Tier 2
  • Deliverables table complete
  • Status is roadmap

Tier 2:

  • Directory created with .feature files
  • Each file has @<prefix>-implements
  • Step definitions stub compiles

Validation:

  • pnpm lint passes
  • pnpm typecheck passes

Handoff Documentation

For multi-session work, capture state at session boundaries.

# Generate handoff from actual annotation state (preferred over manual template)
pnpm process:query -- handoff --pattern <PatternName>
pnpm process:query -- handoff --pattern <PatternName> --git   # include recent commits

The CLI handoff always reflects current annotation state. The template below is for additional context:

Handoff Template

## Session State

- **Last completed:** Phase 1 - Core types
- **In progress:** Phase 2 - Validation
- **Blockers:** None

### Files Modified

- `src/types.ts` - Added core types
- `src/validate.ts` - Started validation (incomplete)

## Next Session

1. **FIRST:** Complete validation in `src/validate.ts`
2. Add integration tests
3. Update deliverable statuses

Discovery Tags

Capture learnings inline during sessions:

# In feature file comments or code:
# @<prefix>-discovered-gap: Missing-edge-case-for-empty-input
# @<prefix>-discovered-improvement: Cache-parsed-results
# @<prefix>-discovered-learning: Gherkin-requires-strict-indentation

See tests/features/behavior/session-handoffs.feature for the full handoff specification.

Quick Reference: FSM Protection

State Protection Can Add Deliverables Needs Unlock
roadmap None Yes No
active Scope-locked No No
completed Hard-locked No Yes
deferred None Yes No

Valid transitions: See METHODOLOGY.md#fsm-enforced-workflow

Related Documentation

Document Content
METHODOLOGY.md Core thesis, FSM states, two-tier architecture
GHERKIN-PATTERNS.md DataTables, DocStrings, Rule blocks
CONFIGURATION.md Tag prefixes, presets
TAXONOMY.md Tag taxonomy concepts and API
PROCESS-API.md Data API CLI commands for all session types
VALIDATION.md CLI flags for lint-patterns and validate-patterns