fix: plan command creates required artifacts (research.md, data-model.md, contracts/, quickstart.md)

Author: kanfil

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to the Specify CLI and templates are documented here.
 
+## [0.3.41] - 2026-04-13
+
+### Fixed
+
+- **adlc.spec.plan**: Plan command now creates all required artifacts
+  - Added imperative Outline section with explicit "CREATE" instructions for each artifact
+  - Fixed bug where agent only wrote plan.md but didn't generate research.md, data-model.md, contracts/, or quickstart.md
+  - Removed ~150 lines of legacy feature architecture content (moved to architect extension hooks)
+  - Consolidated duplicate phase numbering (removed "Core Workflow" Phase 1-2, kept "Phases" Phase 0-1)
+  - Trimmed Triage Framework section from 70 lines to 20 essential criteria
+  - File size reduced from 421 lines to 296 lines (30% reduction)
+  - Root cause: Missing clear execution instructions; agent interpreted phases as documentation rather than actionable steps
+
 ## [0.3.40] - 2026-04-13
 
 ### Fixed

presets/agentic-sdlc/commands/adlc.spec.plan.md

@@ -100,6 +100,25 @@ $ARGUMENTS
 - Timeline or resource considerations
 - Quality or compliance requirements
 
+## Outline (MANDATORY EXECUTION STEPS)
+
+1. **Setup**: Run `{SCRIPT}` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load context**: Read FEATURE_SPEC and `/memory/constitution.md`. Load IMPL_PLAN template (already copied by setup script).
+
+3. **Execute plan workflow** (CREATE ALL ARTIFACTS):
+   - Fill plan.md Technical Context section (mark unknowns as "NEEDS CLARIFICATION")
+   - Fill plan.md Constitution Check section from constitution
+   - Evaluate gates (ERROR if violations unjustified)
+   - **Phase 0: CREATE research.md** - Resolve all NEEDS CLARIFICATION via research
+   - **Phase 1: CREATE data-model.md** - Extract entities from feature spec
+   - **Phase 1: CREATE contracts/** directory with API endpoint definitions (if project has external interfaces)
+   - **Phase 1: CREATE quickstart.md** - Developer setup guide
+   - **Phase 1: RUN agent context update** - Execute `{AGENT_SCRIPT}` to update agent-specific files
+   - Re-evaluate Constitution Check post-design in plan.md
+
+4. **Stop and report**: Command ends after Phase 1 completion. Report branch, IMPL_PLAN path, and all generated artifacts (research.md, data-model.md, contracts/, quickstart.md).
+
 ## Execution Strategy
 
 **Chain of Thought Approach:**
@@ -110,62 +129,19 @@ $ARGUMENTS
 4. **Validate Compliance** → Ensure constitutional alignment
 5. **Generate Artifacts** → Produce implementation-ready documentation
 
-## Core Workflow
-
-### Phase 1: Planning Setup & Context Loading
-
-**Objective:** Establish planning environment and load all required context
-
-1. **Environment Initialization**
-   - Execute: `{SCRIPT}` from repository root
-   - Parse JSON output for: FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH
-   - Validate all required paths exist and are accessible
-   - Handle argument escaping for special characters
-
-### CRITICAL - Path Validation
+## CRITICAL - Path Validation
 
 **DO NOT write to project root directory**
-- Parse `IMPL_PLAN` from script JSON output
+- Parse `IMPL_PLAN` from script JSON output (from `{SCRIPT}`)
 - Write ONLY to `IMPL_PLAN` path - never to `./plan.md`
 - The correct path is: `./specs/<BRANCH>/plan.md` (e.g., `./specs/001-user-auth/plan.md`)
 - Common mistake: Writing to `./plan.md` instead of `./specs/001-user-auth/plan.md`
 
-### Non-Git Repository Support
-
-If working in a non-git repository:
-- Ensure `SPECIFY_FEATURE` environment variable is set (from `/spec.specify`)
-- Run: `export SPECIFY_FEATURE=001-user-auth` (or your feature branch name) before this command
+**Non-Git Repository Support:**
+- If working in a non-git repository, ensure `SPECIFY_FEATURE` environment variable is set (from `/spec.specify`)
 - Without this, the script may fail to find the correct feature directory
 
-2. **Context Acquisition**
-   - **Specification Loading:** Read FEATURE_SPEC for requirements and constraints
-   - **Constitutional Loading:** Read `/memory/constitution.md` for governance rules
-   - **Template Loading:** Load appropriate template
-   - **Validation:** Ensure all context sources are available and consistent
-
-### Phase 2: Technical Analysis & Research Planning
-
-**Objective:** Identify technical scope and knowledge gaps requiring research
-
- 1. **Technical Context Mapping**
-    - Extract technical requirements from feature specification
-    - Identify technology stack and architectural patterns
-    - Map integration points and external dependencies
-    - **NEEDS CLARIFICATION Flag:** Mark unknowns preventing confident planning
-
- 2. **Constitutional Compliance Assessment**
-    - Map feature requirements against constitution principles
-    - Identify potential conflicts or additional requirements
-    - Document compliance strategy and justification
-    - **Gate Evaluation:** Block progression for unjustified violations
-
- 3. **Research Planning**
-    - **Gap Analysis:** Convert NEEDS CLARIFICATION items to research tasks
-    - **Dependency Research:** Plan investigation of critical integrations
-    - **Best Practice Research:** Identify technology-specific recommendations
-    - Generate research.md with prioritized investigation plan
-
-## Execution Flow
+## Phases
 
 ### Phase 0: Outline & Research
 
@@ -214,113 +190,26 @@ If working in a non-git repository:
 
 **Output**: data-model.md, /contracts/* (if external interfaces), quickstart.md, agent-specific file
 
-### Phase 2: Feature Architecture (via architect extension)
-
-**Prerequisites:** Research complete
-
-**Trigger**: architect extension installed and adr.md exists (.specify/drafts/adr.md from system-level architecture)
-
-**Note**: Architecture workflow now handled via architect extension hooks:
-
-**before_plan hook (if architect extension present)**:
-- `/architect.specify`: Create feature-level ADRs
-- `/architect.clarify`: Refine feature ADRs
-- `/architect.implement`: Generate feature AD.md (optional)
-
-**after_plan hook (if architect extension present)**:
-- `/architect.validate --for-plan`: Validate plan alignment with architecture (READ-ONLY)
-- Parse findings: BLOCKING, HIGH-SEVERITY, WARNINGS
-- Document validation report in plan.md
-
-**If architect extension NOT available**:
-- Architecture workflow does not run
-- Plan generation continues with spec-based information only
-
-**Cross-Validation (if architect installed)**:
-1. **Load System Architecture**:
-   - Read `AD.md` (root) for system-level architecture context
-   - Read `.specify/drafts/adr.md` for system-level ADRs
-   - Extract relevant viewpoints and constraints
-
-2. **Identify Feature-Specific Decisions**:
-   - What new components does this feature introduce?
-   - What existing components are modified?
-   - What data entities are added/changed?
-   - What integration points are affected?
-
-3. **Generate Feature ADRs** (via before_plan hook):
-   - Create `specs/{feature}/adr.md` with feature-level decisions
-   - Each ADR should reference system ADRs: "Aligns with ADR-XXX"
-   - Flag any conflicts: "VIOLATION: Conflicts with ADR-XXX"
-
-4. **Generate Feature Architecture Description** (via before_plan hook, \`/architect.implement\`):
-   - Use `templates/feature-AD-template.md` as base
-   - Focus on feature context, functional design, data design
-   - Include integration points with system architecture
-   - Generate feature-specific diagrams
-
-5. **Cross-Validate Against System AD** (via after_plan hook validation):
-   - Verify feature doesn't violate system boundaries
-   - Ensure consistency with system component patterns
-   - Check data model compatibility with Information View
-   - Validate deployment approach fits Deployment View
-
-**Output**:
-
-- `specs/{feature}/adr.md` (feature-level decisions)
-- `specs/{feature}/AD.md` (feature architecture description)
-
 ## Triage Framework: [SYNC] vs [ASYNC] Task Classification
 
-**Purpose**: Guide the classification of implementation tasks as [SYNC] (human-reviewed) or [ASYNC] (agent-delegated) to optimize execution efficiency and quality.
-
-#### Triage Decision Framework
-
-**Evaluate Each Implementation Task Against These Criteria:**
-
-##### [SYNC] Classification (Human Execution Required)
-
-- **Complex Business Logic**: Non-trivial algorithms, state machines, or domain-specific calculations
-- **Architectural Decisions**: System design choices, component boundaries, or integration patterns
-- **Security-Critical Code**: Authentication, authorization, encryption, or data protection
-- **External Integrations**: Third-party APIs, legacy systems, or complex data transformations
-- **Ambiguous Requirements**: Unclear specifications requiring interpretation or clarification
-- **High-Risk Changes**: Database schema changes, API contract modifications, or breaking changes
+**Purpose**: Classify implementation tasks as [SYNC] (human-reviewed) or [ASYNC] (agent-delegated).
 
-##### [ASYNC] Classification (Agent Delegation Suitable)
+**[SYNC] - Human Execution Required:**
+- Complex business logic, algorithms, state machines
+- Security-critical code (auth, encryption, data protection)
+- External integrations, third-party APIs
+- Architectural decisions, component boundaries
+- High-risk changes (schema, API contracts, breaking changes)
 
-- **Well-Defined CRUD**: Standard create/read/update/delete operations with clear schemas
-- **Repetitive Tasks**: Boilerplate code, standard library usage, or template-based generation
-- **Clear Specifications**: Unambiguous requirements with complete acceptance criteria
-- **Independent Components**: Self-contained modules with minimal external dependencies
-- **Standard Patterns**: Established frameworks, libraries, or architectural patterns
-- **Testable Units**: Components with comprehensive automated test coverage
+**[ASYNC] - Agent Delegation Suitable:**
+- Well-defined CRUD operations with clear schemas
+- Boilerplate code, standard library usage
+- Independent components with minimal dependencies
+- Standard framework/library patterns
+- Testable units with comprehensive test coverage
 
-#### Triage Process
-
-1. **Task Identification**: Break down the feature into discrete, implementable tasks
-2. **Criteria Evaluation**: Assess each task against the [SYNC]/[ASYNC] criteria above
-3. **Rationale Documentation**: Record the reasoning for each classification decision
-4. **Risk Assessment**: Consider the impact of incorrect classification
-5. **Review Checkpoint**: Validate triage decisions before task generation
-
-#### Triage Audit Trail
-
-**Document for Each Task:**
-
-- Classification: [SYNC] or [ASYNC]
-- Primary Criteria: Which criteria drove the classification
-- Risk Level: Low/Medium/High (impact of misclassification)
-- Rationale: 1-2 sentence explanation
-
-#### Triage Effectiveness Metrics
-
-**Track Over Time:**
-
-- Classification Accuracy: Percentage of tasks correctly classified (measured post-implementation)
-- Review Efficiency: Time spent on [SYNC] reviews vs [ASYNC] execution time
-- Quality Impact: Defect rates by classification type
-- Learning Opportunities: Common misclassification patterns
+**Triage Output in plan.md:**
+Document each task with: Classification ([SYNC]/[ASYNC]), Primary Criteria, Risk Level, Rationale
 
 ## Key Rules
 
@@ -338,24 +227,10 @@ If working in a non-git repository:
 - Detailed technical analysis and constitutional compliance
 - Complete design artifacts and thorough triage
 
-**Architecture Integration** (via architect extension):
-
-- architect extension hooks handle architecture workflow automatically
-- **before_plan hook**: Create feature ADRs (if before_plan hook configured)
-- **after_plan hook**: Validate plan alignment (READ-ONLY validation via architect.validate)
-- Feature ADRs auto-validated against system ADRs in `.specify/drafts/adr.md`
-- Conflicts flagged as VIOLATION requiring resolution
-- Aligned decisions noted with "Aligns with ADR-XXX"
-
-### Two-Level Architecture System
-
-| Level | Location | ADR File | Architecture Description | Generated By | Hook |
-|-------|----------|----------|--------------------------|--------------|------|
-| **System** | Main branch | `.specify/drafts/adr.md` | `AD.md` (root) or `{TEAM_DIRECTIVES}/AD.md` | `/architect.*` commands | N/A |
-| **Feature** | Feature branch | `specs/{feature}/adr.md` | `specs/{feature}/AD.md` | `/architect.specify → /architect.clarify → /architect.implement` | before_plan |
-| **Validation** | Plan level | READ-ONLY via `/architect.validate --for-plan` | Validates plan alignment | architect extension | after_plan |
-
-Feature architecture inherits and extends system architecture, ensuring consistent governance across all development.
+**Architecture Integration Note**:
+- If architect extension is configured, hooks will handle feature architecture automatically
+- Plan command focuses on research, data modeling, and contracts generation
+- Architecture artifacts (adr.md, AD.md) are managed by architect extension hooks
 
 ### AI-Powered Context/Skills Refresh (Always Enabled)
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentic-sdlc-specify-cli"
-version = "0.3.40"
+version = "0.3.41"
 description = "Specify CLI (tikalk fork). Agentic SDLC toolkit for Spec-Driven Development with pre-installed extensions and AI integrations."
 requires-python = ">=3.11"
 dependencies = [