Skill: Context Summary

Overview

This skill maintains the context/ folder as a wiki - a stable reference for agents to get situational awareness. The context folder is READ-ONLY during active workflows and updated only by the archival skill after workflows complete.

Key Principle: Separation of Concerns

┌─────────────────────────────────────────────────────────────────┐
│  DURING ACTIVE WORKFLOW                                          │
│                                                                  │
│  workflow/active/{name}/        ← WRITE HERE (all agent updates) │
│  context/                       ← READ-ONLY (wiki reference)     │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  AFTER WORKFLOW COMPLETES (Archival Skill)                       │
│                                                                  │
│  workflow/active/{name}/        → Move to workflow/archive/      │
│  context/                       ← UPDATED with learnings         │
└─────────────────────────────────────────────────────────────────┘

Purpose

• Token efficiency - Agents read ~1000 tokens instead of 50,000+ to get context
• Stable reference - Context doesn't change mid-workflow (predictable)
• Historical wiki - Contains learnings from past workflows
• Fresh context per iteration - Each agent spawn reads summaries, not conversation

---

Context Folder Location

The context folder lives in the project root:

project-root/
├── workflow/
│   └── active/                   # Active workflow state (WRITE)
│       └── {workflow-name}/
│           ├── stories/*.md      # Story details during workflow
│           └── ...
│
└── context/                      # Wiki reference (READ-ONLY during workflow)
    ├── solution-summary.md       # Solution overview
    ├── project/                  # Module documentation
    │   └── *.md
    └── stories/                  # Historical stories (from past workflows)
        └── *.md

---

Summary Types

1. Solution Summary (solution-summary.md)

High-level overview of the entire solution. Read by all agents on initialization.

Target size: ~500 tokens

Contains:

• Tech stack and architecture overview
• Key patterns and conventions
• Current sprint focus
• Important constraints

Updated by: Archival skill (after workflows complete)

2. Project Summary (project/{name}-summary.md)

Module/project-specific context. Read only when working on that module.

Target size: ~400 tokens

Contains:

• Module purpose and boundaries
• Key files and structure
• Integration points
• Module-specific patterns

Updated by: Archival skill (when module changes occur)

3. Story Summary (stories/{story_key}.md)

Historical reference from past workflows. These are copies of story files from archived workflows.

Note: During an active workflow, story details live in workflow/active/{name}/stories/. After archival, they're copied here for future reference.

Target size: ~300-500 tokens

Contains:

• Final iteration history
• What was learned
• Patterns discovered

---

Agent Initialization Protocol

When an agent is spawned for a task:

1. Read context/solution-summary.md           (~500 tokens)
         │
         ▼
2. (If working on active workflow)
   Read workflow/active/{name}/workflow.md    (~400 tokens)
   Read workflow/active/{name}/stories/{key}.md (~300-500 tokens)
         │
         ▼
   OR (If no active workflow, just reference)
   Read context/stories/{{story_key}}.md      (historical)
         │
         ▼
3. (If story references a project module)
   Read context/project/{{project}}-summary.md (~400 tokens)
         │
         ▼
4. Read specific files listed in "Relevant Files" section
         │
         ▼
   Total context: ~1000-1500 tokens
   Agent is ready to work

---

During vs After Workflow

During Active Workflow

Folder	Status	Agent Action
workflow/active/{name}/	WRITE	All updates go here
context/	READ-ONLY	Reference only, no updates

After Workflow (Archival Runs)

Action	Source	Destination
Copy stories	workflow/archive/{name}/stories/	context/stories/
Update solution	Learnings from workflow	context/solution-summary.md
Update projects	Module changes	context/project/*.md

---

Example: Solution Summary

# Solution Summary

## Overview
E-commerce platform for artisan bakery products.

## Tech Stack
- **Frontend:** Next.js 14, React, Tailwind CSS
- **Backend:** Next.js API routes, Prisma ORM
- **Database:** PostgreSQL
- **Payments:** Stripe
- **Auth:** NextAuth.js

## Architecture

src/ ├── app/ # Next.js app router pages ├── components/ # React components ├── services/ # Business logic (repository pattern) ├── types/ # TypeScript types └── tests/ # Test files mirror src structure

## Key Patterns
- Repository pattern for data access (`src/services/*Service.ts`)
- TDD: Tests written before implementation
- API routes return typed responses

## Conventions
- Components: PascalCase (`ProductCard.tsx`)
- Services: camelCase (`paymentService.ts`)
- Tests: `*.test.ts` in `__tests__/` folders

## Current Sprint
Sprint 5: Checkout flow implementation

## Constraints
- 100% test pass rate required
- 80% minimum code coverage
- All PRs require Senior review

---

Example: Project Summary

# Project: Checkout Module

## Purpose
Handles the complete checkout flow from cart to order confirmation.

## Boundaries
- Receives cart data from Cart module
- Calls Payment module for processing
- Creates orders in database
- Triggers notifications

## Key Files

src/ ├── app/checkout/ │ ├── page.tsx # Checkout page │ └── confirmation/ │ └── page.tsx # Order confirmation ├── services/ │ ├── checkoutService.ts # Checkout orchestration │ └── orderService.ts # Order CRUD └── tests/checkout/ └── checkoutService.test.ts

## Integration Points
- `cartService.getCart()` - Get current cart
- `paymentService.createPayment()` - Process payment
- `notificationService.sendOrderConfirmation()` - Send email

## Module Patterns
- Checkout is a saga/orchestrator
- Orders are immutable after creation
- All prices in cents (integer)

---

Token Comparison

Approach	Tokens to Get Context
Full conversation history	20,000 - 100,000+
Re-read all docs	10,000 - 30,000
Context summaries	~1,000 - 1,500

90-95% token reduction for agent initialization.

---

Related Skills

• skills/workflow/workflow-tracking/ - Active workflow state (agents update here)
• skills/workflow/workflow-archival/ - Updates context after workflow completion
• skills/quality/gate-definitions/ - Gate thresholds

---

Agents Using This Skill

Agent	Usage
All Agents	READ summaries on initialization
Archival Skill	WRITE updates after workflow completes

Note: Individual agents no longer directly update context/ files. All updates flow through the archival skill.