Workflow Blueprint - 5-Session Project Pattern

This blueprint shows the optimal lean-ctx workflow for a multi-session project. Each session builds on the previous one, leveraging caching, knowledge persistence, and session handoff to minimize redundant work.

The 5-Session Pattern

Session 1: Orientation (15-30 min)

Goal: Understand the project structure and identify the files relevant to your task.

Step 1: Project Overview

ctx_overview task="add user authentication with JWT"
→ Project: my-api (TypeScript/Express)
  Structure: 4 main directories, 42 source files
  Entry: src/index.ts → src/app.ts → src/routes/*
  Key configs: tsconfig.json, package.json, .env.example
  Preloaded: 5 files in optimal modes

Step 2: Explore the Project Tree

ctx_tree depth=3
→ my-api/
    src/ (42)
      routes/ (8)
      middleware/ (3)
      models/ (6)
      services/ (5)
    tests/ (12)
    docs/ (3)
    package.json

Step 3: Read Key Files

# Read the entry point in map mode (understand structure, not details)
ctx_read src/app.ts mode=map
→ F1=app.ts [186L] deps:express,cors,helmet API:fn createApp()→Express

# Read the existing auth if any
ctx_read src/middleware/auth.ts mode=signatures
→ F2=auth.ts [42L] fn requireAuth(req,res,next), fn optionalAuth(req,res,next)

Step 4: Save Session for Next Time

ctx_session action=save
→ Session saved: 5 files cached (F1-F5), task context preserved

Session 2: Implementation (30-60 min)

Goal: Write the core implementation, building on Session 1's cached context.

Step 1: Restore Context

ctx_handoff action=load
→ Restored: 5 cached files (F1-F5), task: "add user authentication with JWT"
  All files still current (no changes detected)

Step 2: Implement

# Read the file you'll edit in full mode
ctx_read src/middleware/auth.ts
→ F2=auth.ts 42L [full content - ready to edit]

# After editing, check changes
ctx_read src/middleware/auth.ts mode=diff
→ F2=auth.ts [diff]
  L5: + import jwt from 'jsonwebtoken';
  L12-28: + [new JWT validation logic]
  [saved 890 tokens (97%)]

Step 3: Checkpoint

ctx_compress
→ Checkpoint created: 8 files, 3 edits tracked

Session 3: Deep Work (30-60 min)

Goal: Handle edge cases, understand impact of changes, integrate with rest of codebase.

Step 1: Impact Analysis

ctx_impact action=analyze path="src/middleware/auth.ts"
→ 8 files depend on auth.ts:
  Direct: src/routes/users.ts, src/routes/admin.ts, src/routes/api.ts
  Transitive: src/services/user.ts → src/models/user.ts
  Tests: tests/auth.test.ts, tests/routes.test.ts

Step 2: Check Call Sites

ctx_callers symbol="requireAuth"
→ 12 callers across 5 files:
  src/routes/users.ts:14  router.get('/profile', requireAuth, ...)
  src/routes/admin.ts:8   router.use(requireAuth)
  ...

Step 3: Graph Visualization

ctx_graph_diagram file="src/middleware/auth.ts" depth=2
→ [Mermaid diagram of auth.ts dependency graph]

Session 4: Testing (20-40 min)

Goal: Write and run tests, fix failures.

# Run existing tests
ctx_shell command="npm test"
→ 38 passed, 4 failed (2.1s)
  FAIL tests/auth.test.ts:23 "should reject expired token"
  FAIL tests/auth.test.ts:45 "should handle missing header"
  [1,600 tok saved (90%)]

# Quick code execution to validate logic
ctx_execute language="typescript" code="
  import jwt from 'jsonwebtoken';
  const token = jwt.sign({userId: 1}, 'secret', {expiresIn: '1h'});
  console.log(jwt.verify(token, 'secret'));
"
→ { userId: 1, iat: ..., exp: ... }  [12 ms]

Session 5: Wrap-up (15-30 min)

Goal: Review changes, document decisions, save knowledge for future sessions.

Step 1: Review Savings

ctx_gain
→ Project total: 89.2% (142,850 tokens saved across 5 sessions)
  Cost saved: ~$1.43 (Claude Sonnet) / ~$7.14 (Claude Opus)

Step 2: Save Knowledge

ctx_knowledge action=remember key="auth-pattern" value="JWT RS256 with 1h expiry, refresh tokens in httpOnly cookies"
→ Knowledge saved: auth-pattern (persists across sessions)

ctx_knowledge action=remember key="gotcha-auth" value="Token validation middleware must check both Authorization header AND cookie"
→ Knowledge saved: gotcha-auth

Step 3: Compress Project Memory

ctx_compress_memory path=".cursorrules"
→ Compressed .cursorrules: 2,400 → 890 tokens (63% savings)
  Backup saved: .cursorrules.original.md