Documentation > Developer Guide > Requirements

---

v1 Core Requirements (33 total)

Foundation (FOUND-01 to FOUND-04)

ID	Requirement	Status
FOUND-01	System stores patterns in .planning/patterns/ as append-only JSONL files	Done
FOUND-02	System stores skills in .claude/skills/ as Markdown files with YAML frontmatter	Done
FOUND-03	Skill format follows Claude Code conventions with trigger and learning extensions	Done
FOUND-04	System maintains skill index for fast discovery without reading all files	Done

---

Core Type Definitions

The requirements above are implemented through three foundational type systems. Below are the real TypeScript interfaces from the codebase.

SkillMetadata: The Skill Type System

From src/types/skill.ts — defines the complete skill metadata interface supporting both official Claude Code fields and gsd-skill-creator extensions:

export interface SkillMetadata {
  // Required by Claude Code
  name: string;           // max 64 chars, lowercase + hyphens only
  description: string;    // max 1024 chars, used for auto-triggering

  // Claude Code optional fields
  'disable-model-invocation'?: boolean;
  'user-invocable'?: boolean;
  'allowed-tools'?: string[] | string;
  'argument-hint'?: string;
  model?: string;
  context?: 'fork';
  agent?: string;
  hooks?: Record<string, unknown>;
  license?: string;
  compatibility?: string;

  // Official metadata container for extensions
  metadata?: {
    extensions?: {
      'gsd-skill-creator'?: GsdSkillCreatorExtension;
      [key: string]: unknown;
    };
  };
}

export interface Skill {
  metadata: SkillMetadata;
  body: string;           // Markdown content
  path: string;           // File path for reference
}

Pattern: The Observation Type System

From src/types/pattern.ts — defines the base pattern structure used for all observation categories:

export type PatternCategory =
  | 'commands' | 'decisions' | 'workflows'
  | 'contexts' | 'sessions' | 'events'
  | 'executions' | 'feedback' | 'lineage';

export interface Pattern {
  timestamp: number;      // Unix timestamp ms
  category: PatternCategory;
  data: Record<string, unknown>;  // Category-specific payload
}

export interface CommandPattern extends Pattern {
  category: 'commands';
  data: {
    command: string;
    args?: string[];
    context?: Record<string, unknown>;
  };
}

export interface DecisionPattern extends Pattern {
  category: 'decisions';
  data: {
    decision: string;
    options?: string[];
    chosen?: string;
    rationale?: string;
  };
}

SessionObservation: The Session Tracking Type

From src/types/observation.ts — captures complete session summaries with metrics, active skills, and tier discriminants:

export interface SessionObservation {
  sessionId: string;
  startTime: number;
  endTime: number;
  durationMinutes: number;
  source: 'startup' | 'resume' | 'clear' | 'compact';
  reason: 'clear' | 'logout' | 'prompt_input_exit' | 'bypass_permissions_disabled' | 'other';
  metrics: SessionMetrics;
  topCommands: string[];
  topFiles: string[];
  topTools: string[];
  activeSkills: string[];    // Skills active during this session (AGENT-01)
  tier?: ObservationTier;    // Storage routing: 'ephemeral' | 'persistent'
  squashedFrom?: number;     // Observations squashed into this one
}

export interface SessionMetrics {
  userMessages: number;
  assistantMessages: number;
  toolCalls: number;
  uniqueFilesRead: number;
  uniqueFilesWritten: number;
  uniqueCommandsRun: number;
}

SkillTrigger: Auto-Activation Conditions

From src/types/skill.ts — defines the trigger system that maps intents, file patterns, and contexts to skill activation:

export interface SkillTrigger {
  intents?: string[];    // Match user intent patterns (regex or keywords)
  files?: string[];      // Match file patterns being worked on (glob)
  contexts?: string[];   // Match context patterns (e.g., "in GSD planning phase")
  threshold?: number;    // Minimum confidence score to activate (0-1)
}

export interface SkillLearning {
  applicationCount?: number;    // How many times skill has been applied
  feedbackScores?: number[];    // User feedback scores (1-5)
  corrections?: SkillCorrection[];  // Corrections/overrides captured
  lastRefined?: string;         // Last refinement timestamp
}

---

Milestone Summary

Total: 806 requirements across 28 milestones, all implemented.