grimoire-framework 1.0.0

package/.grimoire/development/tasks/plan-create-context.md

@@ -0,0 +1,812 @@
+# Plan Pipeline: Create Context
+
+> **Phase:** execution-context
+> **Owner Agent:** @architect
+> **Pipeline:** plan-pipeline
+
+---
+
+## Purpose
+
+Gera os arquivos de contexto necessários para a fase de planejamento/implementação de uma story. Extrai informações do projeto (stack, convenções, padrões) e identifica arquivos relevantes para o escopo do story.
+
+**Key Outputs:**
+
+- `project-context.yaml` - Stack tecnológico, convenções, e padrões do projeto
+- `files-context.yaml` - Arquivos relevantes para implementação do story
+
+---
+
+## autoClaude
+
+```yaml
+autoClaude:
+  version: '3.0'
+  pipelinePhase: execution-context
+
+  elicit: false # Runs automatically without user interaction
+  deterministic: true # Same inputs should yield same context
+  composable: true
+
+  inputs:
+    - name: storyId
+      type: string
+      required: true
+      description: ID da story sendo contextualizada
+
+    - name: storyPath
+      type: file
+      path: docs/stories/{storyId}/**/*.md
+      required: false
+      description: Path alternativo para o story (se não seguir convenção)
+
+    - name: specPath
+      type: file
+      path: docs/stories/{storyId}/spec/
+      required: false
+      description: Spec existente do story (se disponível)
+
+    - name: forceRefresh
+      type: boolean
+      required: false
+      default: false
+      description: Força regeneração mesmo se contexto existir
+
+  outputs:
+    - name: project-context.yaml
+      type: file
+      path: docs/stories/{storyId}/plan/project-context.yaml
+      schema: project-context-schema
+
+    - name: files-context.yaml
+      type: file
+      path: docs/stories/{storyId}/plan/files-context.yaml
+      schema: files-context-schema
+
+  verification:
+    type: schema
+    schemaRef: context-schemas
+
+  contextRequirements:
+    projectContext: false # This task GENERATES project context
+    filesContext: false # This task GENERATES files context
+    implementationPlan: false
+    spec: true # Needs spec to understand story scope
+```
+
+---
+
+## Data Sources
+
+### Source 1: Core Configuration
+
+```yaml
+source: core-config
+location: .grimoire/core-config.yaml
+
+extract:
+  - project.type # EXISTING_grimoire, GREENFIELD, etc.
+  - project.version # Framework version
+  - ide.selected # Active IDEs
+  - github.semantic_release.enabled
+  - autoClaude.version # ADE version
+  - devStoryLocation # Story path convention
+  - scriptsLocation # Utility locations
+```
+
+### Source 2: Tech Stack Documentation
+
+```yaml
+source: tech-stack
+locations:
+  - docs/framework/tech-stack.md # Primary
+  - docs/architecture/tech-stack.md # Fallback
+
+extract:
+  - runtime: 'Node.js version, package manager'
+  - language: 'JavaScript/TypeScript standards'
+  - dependencies: 'Core dependencies and versions'
+  - testing: 'Testing framework (Jest, Vitest)'
+  - linting: 'ESLint, Prettier configs'
+  - build: 'Build tools and scripts'
+```
+
+### Source 3: Source Tree Documentation
+
+```yaml
+source: source-tree
+locations:
+  - docs/framework/source-tree.md # Primary
+  - docs/architecture/source-tree.md # Fallback
+
+extract:
+  - directory_structure: 'Key directories and purposes'
+  - file_patterns: 'Naming conventions'
+  - placement_rules: 'Where to put new files'
+```
+
+### Source 4: Package Manifest
+
+```yaml
+source: package-json
+location: package.json
+
+extract:
+  - name: 'Package name'
+  - version: 'Current version'
+  - dependencies: 'Production dependencies'
+  - devDependencies: 'Development dependencies'
+  - scripts: 'Available npm scripts'
+```
+
+### Source 5: TypeScript Configuration
+
+```yaml
+source: tsconfig
+location: tsconfig.json
+
+extract:
+  - compilerOptions.target: 'JS target version'
+  - compilerOptions.module: 'Module system'
+  - compilerOptions.strict: 'Strict mode enabled'
+  - paths: 'Path aliases'
+```
+
+---
+
+## Execution Flow
+
+### Step 1: Validate Inputs
+
+```yaml
+validation:
+  action: validate_story_exists
+
+  steps:
+    - id: check-story-path
+      description: 'Verify story directory exists'
+      action: |
+        Check if docs/stories/{storyId}/ exists
+        OR if custom storyPath provided and exists
+
+    - id: check-spec-exists
+      description: 'Look for spec directory'
+      action: |
+        Check for docs/stories/{storyId}/spec/
+        If not found, proceed with story-level analysis only
+
+    - id: check-existing-context
+      description: 'Check if context already exists'
+      action: |
+        If docs/stories/{storyId}/plan/project-context.yaml exists
+        AND forceRefresh = false
+        THEN skip regeneration (return existing)
+```
+
+### Step 2: Extract Project Context
+
+```yaml
+project_extraction:
+  action: gather_project_info
+
+  steps:
+    - id: read-core-config
+      description: 'Parse .grimoire/core-config.yaml'
+      action: |
+        1. Load YAML file
+        2. Extract project metadata
+        3. Extract IDE configuration
+        4. Extract framework settings
+
+    - id: read-tech-stack
+      description: 'Parse tech-stack documentation'
+      action: |
+        1. Try docs/framework/tech-stack.md first
+        2. Fallback to docs/architecture/tech-stack.md
+        3. Extract runtime, language, testing info
+        4. Note any deprecated warnings
+
+    - id: read-source-tree
+      description: 'Parse source-tree documentation'
+      action: |
+        1. Try docs/framework/source-tree.md first
+        2. Fallback to docs/architecture/source-tree.md
+        3. Extract directory structure patterns
+        4. Extract file naming conventions
+
+    - id: read-package-json
+      description: 'Parse package.json'
+      action: |
+        1. Load package.json
+        2. Extract name, version
+        3. Identify key dependencies
+        4. List available npm scripts
+
+    - id: read-tsconfig
+      description: 'Parse tsconfig.json (if exists)'
+      action: |
+        1. Check if tsconfig.json exists
+        2. Extract compiler options
+        3. Extract path aliases
+        4. Note strict mode settings
+```
+
+### Step 3: Analyze Story Scope
+
+```yaml
+scope_analysis:
+  action: determine_relevant_files
+
+  steps:
+    - id: parse-story-content
+      description: 'Extract story requirements'
+      action: |
+        1. Read story markdown file
+        2. Extract acceptance criteria
+        3. Identify mentioned components/modules
+        4. List any explicit file references
+
+    - id: parse-spec-if-exists
+      description: 'Extract spec requirements'
+      action: |
+        1. If spec/requirements.json exists, load it
+        2. Extract functional requirements
+        3. Extract technical constraints
+        4. Note any architecture decisions
+
+    - id: identify-affected-areas
+      description: 'Map story to codebase areas'
+      action: |
+        Based on story content, identify:
+        - Components likely to be modified
+        - Services/APIs involved
+        - Database/schema changes
+        - Test files needed
+
+    - id: search-similar-patterns
+      description: 'Find existing similar implementations'
+      action: |
+        1. Extract key concepts from story
+        2. Search codebase for similar patterns
+        3. Identify reusable components
+        4. Note exemplar implementations
+```
+
+### Step 4: Generate Outputs
+
+```yaml
+output_generation:
+  action: create_context_files
+
+  steps:
+    - id: ensure-plan-directory
+      description: 'Create plan directory if needed'
+      action: |
+        mkdir -p docs/stories/{storyId}/plan/
+
+    - id: generate-project-context
+      description: 'Create project-context.yaml'
+      template: project-context-template
+
+    - id: generate-files-context
+      description: 'Create files-context.yaml'
+      template: files-context-template
+
+    - id: validate-outputs
+      description: 'Validate generated files'
+      action: |
+        1. Parse generated YAML files
+        2. Validate against schemas
+        3. Check for required fields
+```
+
+---
+
+## Output Templates
+
+### project-context.yaml Template
+
+```yaml
+# Auto-generated by @architect *create-context
+# Story: {storyId}
+# Generated: {timestamp}
+
+project:
+  name: '{package.name}'
+  version: '{package.version}'
+  type: '{core-config.project.type}'
+
+  stack:
+    runtime: '{tech-stack.runtime}'
+    language: '{tech-stack.language}'
+    testing: '{tech-stack.testing}'
+    linting: '{tech-stack.linting}'
+
+  conventions:
+    naming:
+      files: '{source-tree.file_patterns.files}'
+      directories: '{source-tree.file_patterns.directories}'
+      components: '{extracted from codebase analysis}'
+    imports:
+      style: '{tsconfig.paths based or relative}'
+      alias: '{tsconfig.paths if present}'
+
+  patterns:
+    state: '{detected state management pattern}'
+    api: '{detected API pattern}'
+    components: '{detected component pattern}'
+    testing: '{detected testing pattern}'
+
+  scripts:
+    test: '{package.scripts.test}'
+    lint: '{package.scripts.lint}'
+    build: '{package.scripts.build}'
+    dev: '{package.scripts.dev}'
+
+  directories:
+    source: '{main source directory}'
+    tests: '{test directory}'
+    stories: '{devStoryLocation}'
+    agents: '{scriptsLocation.development or .grimoire/development/agents}'
+
+metadata:
+  generatedBy: '@architect'
+  generatedAt: '{ISO timestamp}'
+  sources:
+    - '.grimoire/core-config.yaml'
+    - 'docs/framework/tech-stack.md'
+    - 'docs/framework/source-tree.md'
+    - 'package.json'
+    - 'tsconfig.json'
+```
+
+### files-context.yaml Template
+
+```yaml
+# Auto-generated by @architect *create-context
+# Story: {storyId}
+# Generated: {timestamp}
+
+storyId: '{storyId}'
+storyPath: 'docs/stories/{storyId}/'
+specAvailable: { true|false }
+
+relevantFiles:
+  # Files that should be modified
+  toModify:
+    - path: '{detected file path}'
+      purpose: '{why this file is relevant}'
+      confidence: high|medium|low
+      reason: '{detection reason}'
+
+  # Files with similar patterns to follow
+  exemplars:
+    - path: '{similar implementation path}'
+      purpose: '{what pattern to follow}'
+      keyPatterns:
+        - '{pattern 1}'
+        - '{pattern 2}'
+
+  # Files to be aware of (dependencies, configs)
+  dependencies:
+    - path: '{dependency file}'
+      relationship: '{how it relates to the story}'
+
+  # Test files needed
+  tests:
+    - path: '{test file path}'
+      type: unit|integration|e2e
+      status: exists|needed
+
+searchQueries:
+  # Queries used to find relevant files
+  - query: '{search query used}'
+    results: { number of results }
+
+storyAnalysis:
+  # Summary of story scope
+  components:
+    - '{component 1}'
+    - '{component 2}'
+  modules:
+    - '{module 1}'
+  estimatedFiles:
+    new: { count }
+    modified: { count }
+    deleted: { count }
+
+metadata:
+  generatedBy: '@architect'
+  generatedAt: '{ISO timestamp}'
+  storyParsed: true|false
+  specParsed: true|false
+```
+
+---
+
+## Output Schemas
+
+### project-context-schema
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["project", "metadata"],
+  "properties": {
+    "project": {
+      "type": "object",
+      "required": ["name", "stack"],
+      "properties": {
+        "name": { "type": "string" },
+        "version": { "type": "string" },
+        "type": { "type": "string" },
+        "stack": {
+          "type": "object",
+          "properties": {
+            "runtime": { "type": "string" },
+            "language": { "type": "string" },
+            "testing": { "type": "string" },
+            "linting": { "type": "string" }
+          }
+        },
+        "conventions": { "type": "object" },
+        "patterns": { "type": "object" },
+        "scripts": { "type": "object" },
+        "directories": { "type": "object" }
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "required": ["generatedBy", "generatedAt"],
+      "properties": {
+        "generatedBy": { "type": "string" },
+        "generatedAt": { "type": "string", "format": "date-time" },
+        "sources": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}
+```
+
+### files-context-schema
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["storyId", "relevantFiles", "metadata"],
+  "properties": {
+    "storyId": { "type": "string" },
+    "storyPath": { "type": "string" },
+    "specAvailable": { "type": "boolean" },
+    "relevantFiles": {
+      "type": "object",
+      "properties": {
+        "toModify": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["path", "purpose"],
+            "properties": {
+              "path": { "type": "string" },
+              "purpose": { "type": "string" },
+              "confidence": { "enum": ["high", "medium", "low"] },
+              "reason": { "type": "string" }
+            }
+          }
+        },
+        "exemplars": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["path", "purpose"],
+            "properties": {
+              "path": { "type": "string" },
+              "purpose": { "type": "string" },
+              "keyPatterns": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        },
+        "dependencies": { "type": "array" },
+        "tests": { "type": "array" }
+      }
+    },
+    "searchQueries": { "type": "array" },
+    "storyAnalysis": { "type": "object" },
+    "metadata": {
+      "type": "object",
+      "required": ["generatedBy", "generatedAt"],
+      "properties": {
+        "generatedBy": { "type": "string" },
+        "generatedAt": { "type": "string", "format": "date-time" },
+        "storyParsed": { "type": "boolean" },
+        "specParsed": { "type": "boolean" }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Integration
+
+### Command Integration (@architect)
+
+```yaml
+command:
+  name: '*create-context'
+  syntax: '*create-context {story-id} [--force]'
+  agent: architect
+
+  examples:
+    - '*create-context 4.2'
+    - '*create-context STORY-42 --force'
+    - '*create-context grimoire-migration/story-6.1.2.5'
+
+  options:
+    - name: --force
+      description: Force regeneration even if context exists
+      default: false
+```
+
+### Pipeline Integration
+
+```yaml
+pipeline:
+  phase: execution-context
+  standalone: true # Can run independently
+
+  # When run as part of plan-pipeline:
+  previous_phase: spec-critique # Or spec-write if no critique
+  next_phase: plan-implementation
+
+  pass_to_next:
+    - project-context.yaml
+    - files-context.yaml
+
+  # Can also be triggered standalone before implementation
+  triggers:
+    - 'Before *develop-story if context missing'
+    - 'Manual via *create-context'
+```
+
+### Usage in Implementation Plan
+
+```yaml
+consumption:
+  by_task: plan-implementation
+  usage: |
+    The implementation plan task reads these context files to:
+    1. Understand project conventions when generating code
+    2. Identify files to create/modify
+    3. Find exemplar patterns to follow
+    4. Know which tests to create
+
+  by_agent: dev
+  usage: |
+    @dev reads context before implementing to:
+    1. Follow naming conventions
+    2. Use correct import styles
+    3. Know where to place new files
+    4. Reference similar implementations
+```
+
+---
+
+## Error Handling
+
+```yaml
+errors:
+  - id: story-not-found
+    condition: 'Story directory does not exist'
+    action: 'Halt and report story not found'
+    blocking: true
+    message: "Story '{storyId}' not found. Check path and try again."
+
+  - id: core-config-missing
+    condition: '.grimoire/core-config.yaml not found'
+    action: 'Use defaults, warn user'
+    blocking: false
+    fallback: |
+      Use sensible defaults:
+      - project.type: UNKNOWN
+      - ide.selected: [claude-code]
+
+  - id: tech-stack-missing
+    condition: 'No tech-stack.md found in any location'
+    action: 'Infer from package.json'
+    blocking: false
+    fallback: |
+      Analyze package.json to determine:
+      - Runtime from engines.node
+      - Testing from devDependencies (jest/vitest)
+      - Language from typescript presence
+
+  - id: no-relevant-files
+    condition: 'Could not identify any relevant files'
+    action: 'Generate minimal context, flag for review'
+    blocking: false
+    output: |
+      Generate context with empty relevantFiles.toModify
+      Set confidence: low on all findings
+      Add warning in metadata
+
+  - id: parse-error
+    condition: 'YAML/JSON parse error'
+    action: 'Report specific file and error, halt'
+    blocking: true
+```
+
+---
+
+## Examples
+
+### Example 1: Basic Story Context Generation
+
+**Input:** `*create-context 4.2`
+
+**Execution:**
+
+```
+1. Check docs/stories/4.2/ exists ✓
+2. Check docs/stories/4.2/spec/ exists → No spec found
+3. Read .grimoire/core-config.yaml ✓
+4. Read docs/framework/tech-stack.md ✓
+5. Read docs/framework/source-tree.md ✓
+6. Read package.json ✓
+7. Read tsconfig.json ✓
+8. Parse story content for scope
+9. Search codebase for similar patterns
+10. Generate outputs
+```
+
+**Output:** `docs/stories/4.2/plan/project-context.yaml`
+
+```yaml
+project:
+  name: '@grimoire/grimoire'
+  version: '2.3.0'
+  type: EXISTING_grimoire
+
+  stack:
+    runtime: 'Node.js 18+'
+    language: 'JavaScript ES2022 (TypeScript for types)'
+    testing: 'Jest 30.x'
+    linting: 'ESLint 9.x + Prettier 3.x'
+
+  conventions:
+    naming:
+      files: 'kebab-case'
+      directories: 'kebab-case'
+      components: 'PascalCase'
+    imports:
+      style: 'CommonJS (require/module.exports)'
+      alias: 'None (relative paths)'
+
+  patterns:
+    state: 'N/A (CLI tool)'
+    api: 'Commander.js for CLI, execa for subprocesses'
+    components: 'Markdown with YAML frontmatter'
+    testing: 'Jest with describe/it blocks'
+
+  scripts:
+    test: 'jest'
+    lint: 'eslint . --fix'
+    build: 'npm run build'
+    dev: 'node bin/grimoire.js'
+
+  directories:
+    source: '.grimoire/'
+    tests: 'tests/'
+    stories: 'docs/stories'
+    agents: '.grimoire/development/agents'
+
+metadata:
+  generatedBy: '@architect'
+  generatedAt: '2026-01-28T12:00:00Z'
+  sources:
+    - '.grimoire/core-config.yaml'
+    - 'docs/framework/tech-stack.md'
+    - 'docs/framework/source-tree.md'
+    - 'package.json'
+    - 'tsconfig.json'
+```
+
+### Example 2: Story with Spec Available
+
+**Input:** `*create-context STORY-42` (with spec/requirements.json present)
+
+**Additional Output:** `docs/stories/STORY-42/plan/files-context.yaml`
+
+```yaml
+storyId: 'STORY-42'
+storyPath: 'docs/stories/STORY-42/'
+specAvailable: true
+
+relevantFiles:
+  toModify:
+    - path: '.grimoire/development/tasks/spec-gather-requirements.md'
+      purpose: 'Update task to include new elicitation method'
+      confidence: high
+      reason: 'Mentioned in acceptance criteria AC-1'
+
+    - path: '.grimoire/core/elicitation/elicitation-engine.js'
+      purpose: 'Add new question type'
+      confidence: medium
+      reason: 'Inferred from requirement FR-2'
+
+  exemplars:
+    - path: '.grimoire/development/tasks/spec-assess-complexity.md'
+      purpose: 'Follow same V3 autoClaude format'
+      keyPatterns:
+        - 'autoClaude section with version 3.0'
+        - 'inputs/outputs YAML structure'
+        - 'Error handling section'
+
+    - path: '.grimoire/core/elicitation/session/session-manager.js'
+      purpose: 'Similar state management pattern'
+      keyPatterns:
+        - 'Class-based structure'
+        - 'Async methods'
+        - 'Event emission'
+
+  dependencies:
+    - path: '.grimoire/core-config.yaml'
+      relationship: 'May need new config key'
+
+  tests:
+    - path: 'tests/unit/elicitation-engine.test.js'
+      type: unit
+      status: exists
+
+    - path: 'tests/integration/spec-pipeline.test.js'
+      type: integration
+      status: needed
+
+searchQueries:
+  - query: 'elicitation'
+    results: 12
+  - query: 'spec-pipeline'
+    results: 5
+
+storyAnalysis:
+  components:
+    - 'ElicitationEngine'
+    - 'SpecPipeline'
+  modules:
+    - 'core/elicitation'
+    - 'development/tasks'
+  estimatedFiles:
+    new: 1
+    modified: 3
+    deleted: 0
+
+metadata:
+  generatedBy: '@architect'
+  generatedAt: '2026-01-28T12:00:00Z'
+  storyParsed: true
+  specParsed: true
+```
+
+---
+
+## Metadata
+
+```yaml
+metadata:
+  story: '4.2'
+  epic: 'Epic 4 - Execution Engine'
+  created: '2026-01-28'
+  author: '@architect (Aria)'
+  version: '1.0.0'
+  tags:
+    - plan-pipeline
+    - context-generation
+    - project-analysis
+    - prompt-engineering
+    - deterministic
+```
+
+