diff --git a/openspec/changes/add-architectural-decision-records/design.md b/openspec/changes/add-architectural-decision-records/design.md new file mode 100644 index 000000000..a8880deec --- /dev/null +++ b/openspec/changes/add-architectural-decision-records/design.md @@ -0,0 +1,353 @@ +# Design: Architectural Decision Records + +## Context + +OpenSpec currently only supports functional specifications (specs) which document behavioral requirements. However, software projects need to document architectural decisions that cross-cut multiple specs - decisions about technology choices, infrastructure patterns, security approaches, and other non-functional concerns. + +ADRs are a well-established pattern in software architecture (popularized by Michael Nygard) for documenting architectural decisions in a lightweight, version-controlled format. + +**Stakeholders**: AI agents, developers, architects, technical leads + +**Constraints**: +- Must not disrupt existing spec workflow +- Must use the same delta-based change process for consistency +- Must integrate seamlessly with existing CLI commands +- Must be parseable by AI agents to influence future proposals + +## Goals / Non-Goals + +### Goals +- Add parallel ADR structure alongside specs +- Support customizable ADR templates per project +- Integrate ADRs into existing CLI commands (list, show, validate, archive) +- Make ADRs available to AI agents for context when creating proposals +- Use the same delta-based change workflow as specs + +### Non-Goals +- Replacing or modifying the existing spec system +- Adding complex ADR-specific tooling beyond basic CRUD operations +- Enforcing strict ADR format beyond basic validation +- Automatic ADR generation or inference from code + +## Decisions + +### Decision 1: Parallel Structure to Specs + +**What**: Create `adrs/` directory at the same level as `specs/`, with similar structure: +``` +openspec/ +├── specs/ # Functional specifications +│ └── [capability]/ +│ └── spec.md +├── adrs/ # Architectural decisions +│ └── [decision-name]/ +│ └── adr.md +└── changes/ + └── [change-name]/ + ├── specs/ # Spec deltas + └── adrs/ # ADR deltas +``` + +**Why**: +- **Cross-cutting nature**: ADRs affect multiple specs, so they can't be nested within a single spec + - Example: "Use DynamoDB for non-SQL storage" affects user-auth, session-management, analytics, etc. + - Placing ADRs at the top level (parallel to specs) reflects their one-to-many relationship +- Clear separation of concerns (functional vs architectural) +- Familiar structure for users already using specs +- Easy to understand which documents serve which purpose +- Each ADR declares its scope (which specs it affects) rather than being owned by one spec + +**Alternatives considered**: +- ADRs nested within specs → Rejected: ADRs are cross-cutting; they don't belong to one spec +- Single unified document type with metadata tags → Rejected: Too complex, loses clarity +- ADRs as metadata within specs → Rejected: Pollutes functional specs with architectural details +- Separate repo for ADRs → Rejected: Breaks cohesion, harder to keep in sync +- Multiple ADR copies (one per affected spec) → Rejected: Duplication, inconsistency risk + +### Decision 2: Delta-Based Change Workflow for ADRs + +**What**: ADR changes follow the same pattern as spec changes: +```markdown +## ADDED Decisions +### Decision: Technology Choice +... + +## MODIFIED Decisions +### Decision: Existing Decision +... + +## REMOVED Decisions +### Decision: Deprecated Pattern +... +``` + +**Why**: +- Consistency with existing workflow reduces cognitive load +- Reuse existing validation and archiving infrastructure +- AI agents already understand delta format + +**Alternatives considered**: +- Immutable ADRs (new ADR supersedes old) → Rejected: Doesn't match OpenSpec's delta approach +- Freeform ADR updates without deltas → Rejected: Loses traceability and validation + +### Decision 3: Template System + +**What**: Three-tier template resolution: +1. Project-specific template: `openspec/templates/adr.md` +2. Global config template (future): `~/.openspec/templates/adr.md` +3. Built-in default template: `src/core/templates/adr.md` + +Template configuration in `openspec/config.yaml`: +```yaml +templates: + adr: ./templates/adr.md # Optional override +``` + +**Why**: +- Projects have different ADR needs (microservices vs monolith, security-focused vs startup) +- Default template provides good starting point +- Gradual adoption - templates are optional + +**Alternatives considered**: +- No templates, freeform ADRs → Rejected: Loses structure, harder to validate +- Only built-in template → Rejected: Inflexible for diverse projects +- Multiple template types → Rejected: Over-engineering for v1 + +### Decision 4: Two-File ADR Structure + +**What**: Split ADRs into two files for context efficiency: + +**File 1: decision.md** (Concise summary, always loaded) +```markdown +# Decision: [Name] + +**Status:** Accepted | Proposed | Superseded + +**Scope:** [Pattern-based description, not exhaustive list] +Examples: "All capabilities requiring non-relational data storage" + +**What:** [One-sentence summary of the decision] + +**Key Trade-offs:** +- ✓ Managed service, scales automatically +- ✓ Proven at scale +- ✗ Vendor lock-in +- ✗ Higher cost at low scale + +**See:** [Full ADR](./adr.md) for detailed context and analysis. +``` + +**File 2: adr.md** (Full rationale, loaded on-demand) +```markdown +# ADR: [Decision Name] + +## Context +[Detailed background, problem statement, constraints, stakeholders] + +## Options Considered +### Option 1: [Name] +- Pros: [Comprehensive list] +- Cons: [Comprehensive list] +- Cost analysis: [Details] + +### Option 2: [Name] +[Full analysis...] + +## Decision Rationale +[Detailed explanation of why this option was chosen] + +## Consequences +[Detailed impacts, migration considerations, rollback strategy] + +## References +- [Related specs, ADRs, external resources] +``` + +**Directory structure:** +``` +adrs/database-strategy/ +├── decision.md # ~200 tokens - always in context +└── adr.md # ~800-1500 tokens - reference/on-demand +``` + +**Why**: +- **Context efficiency**: 20 ADRs × 200 tokens = 4K (vs 20K for full ADRs) +- **Quick reference**: AI sees all decisions without loading full rationale +- **On-demand detail**: Full analysis available when needed +- **User-friendly**: Quick scan of decision.md, deep dive into adr.md when needed +- **Scope flexibility**: Pattern-based descriptions, not exhaustive lists to maintain + +**Alternatives considered**: +- Single file with separator comments → Rejected: Harder to parse, less clear +- Only decision.md (no full rationale) → Rejected: Loses valuable context +- Summary in frontmatter → Rejected: Not as flexible, harder to read +- Database/structured storage → Rejected: Over-engineering, breaks markdown simplicity + +### Decision 5: CLI Integration Strategy + +**What**: Extend existing commands with ADR support rather than creating ADR-specific commands: +- `openspec list --adrs` instead of `openspec adr list` +- `openspec show [name] --type adr` for disambiguation +- `openspec validate [change]` validates both specs and ADRs +- `openspec archive [change]` archives both specs and ADRs + +**Why**: +- Consistent with verb-first CLI design principle (from openspec-conventions) +- Reduces command proliferation +- Natural workflow - users think about "changes" not "spec changes" vs "ADR changes" + +**Alternatives considered**: +- Separate `openspec adr` command namespace → Rejected: Violates verb-first principle, creates fragmentation +- Automatic detection without flags → Rejected: Ambiguous, harder to script + +### Decision 6: AI Context Integration + +**What**: Update instruction loader to include ADRs when providing context to AI agents: +``` +Context provided: +- specs/ - Functional specifications +- adrs/ - Architectural decisions +- changes/ - Pending proposals +``` + +When AI creates proposals, it should reference relevant ADRs in design.md and tasks. + +**Why**: +- ADRs only valuable if they influence implementation +- AI can check consistency with architectural decisions +- Reduces need for users to repeat architectural context + +**Alternatives considered**: +- Manual ADR references only → Rejected: Easy to forget, inconsistent +- ADR validation blocks conflicting proposals → Rejected: Too rigid for v1 + +### Decision 7: Proactive ADR Detection + +**What**: AI agents automatically detect when architectural decisions are embedded in user requests and create ADRs without requiring explicit user request. + +**Example workflow**: +``` +User: "Create a login feature with session storage" + +AI analysis: +1. "login feature" → functional spec needed (user-auth) +2. "session storage" → architectural decision (database choice) +3. Check: ADR for data storage exists? No → create one + +AI creates change: +changes/add-login/ +├── adrs/database-strategy/ +│ ├── decision.md # ADDED: DynamoDB for sessions +│ └── adr.md +└── specs/user-auth/ + └── spec.md # ADDED: References database-strategy ADR +``` + +**Detection heuristics** documented in AGENTS.md: +- Technology selection (database, framework, library, language) +- Infrastructure choices (hosting, deployment, CI/CD) +- Security approaches (auth method, encryption strategy) +- Cross-cutting patterns (logging, monitoring, error handling) +- Data storage strategies (database type, caching) + +**Why**: +- **Prevents decision burial**: Architectural decisions won't be hidden in spec implementation details +- **Enforces single source of truth**: Database choice becomes reusable ADR, not repeated across specs +- **Better AI behavior**: AI extracts architectural decisions automatically, user doesn't need to know ADR system +- **Natural workflow**: User describes feature, AI structures it properly (ADR + spec) +- **Consistency**: All projects using OpenSpec will capture architectural decisions uniformly + +**Alternatives considered**: +- Require users to explicitly request ADRs → Rejected: Users won't know when ADRs are needed, decisions get buried in specs +- Create ADRs only when user says "create an ADR" → Rejected: Misses the point of automated extraction +- No proactive detection, rely on post-hoc refactoring → Rejected: Decisions already scattered across specs by then +- Strict rules forcing ADRs → Rejected: Too rigid, ADRs should be optional but encouraged + +**Implementation approach**: +- Add detection guidance to AGENTS.md with decision tree +- Update instruction-loader to include ADR checking in proposal workflow +- Add scenarios to change-creation spec about extracting decisions +- Provide concrete examples in docs + +## Risks / Trade-offs + +### Risk 1: Template Complexity +**Risk**: Users may create overly complex templates that are hard to work with +**Mitigation**: +- Provide simple, well-documented default template +- Document template best practices in AGENTS.md +- Keep validation minimal to not enforce rigidity + +### Risk 2: Spec vs ADR Boundary Confusion +**Risk**: Users may be unclear when to use specs vs ADRs +**Mitigation**: +- Clear documentation with examples +- Simple rule: functional behavior = spec, architectural choice = ADR +- ADRs can reference multiple specs they influence + +### Risk 3: Delta Format Mismatch +**Risk**: ADR structure might not fit delta operations as cleanly as specs +**Mitigation**: +- Design ADR format with deltas in mind (decision-level granularity) +- Support MODIFIED for updating existing decisions +- Allow REMOVED with superseding ADR reference + +### Risk 4: Increased Cognitive Load +**Risk**: Two parallel documentation systems could confuse users +**Mitigation**: +- Clear visual distinction in CLI output (icons, colors) +- Consistent workflow reduces learning curve +- Optional adoption - teams can use specs only if preferred + +### Risk 5: Over-Creating ADRs +**Risk**: AI might create too many ADRs for decisions that don't need them +**Mitigation**: +- Clear heuristics in AGENTS.md for when NOT to create ADRs +- Emphasize: ADRs are for cross-cutting/architectural decisions only +- Examples of what should NOT be ADRs (feature-specific implementation details) +- Human review during proposal stage can reject unnecessary ADRs +- ADRs are optional - users can delete proposed ADRs before archiving + +## Migration Plan + +### Phase 1: Core Implementation +1. Implement template system and default ADR template +2. Add ADR parser and validation +3. Extend CLI commands (list, show, validate, archive) +4. Update AGENTS.md with ADR workflow + +### Phase 2: Testing & Refinement +1. Manual testing with sample ADR changes +2. Cross-platform path testing +3. Validate AI context integration +4. Gather feedback on default template + +### Phase 3: Documentation & Rollout +1. Update all affected specs with deltas +2. Create example ADRs for OpenSpec itself (e.g., "Why TypeScript", "Why Delta Format") +3. Announce feature with migration guide + +### Rollback Strategy +If ADRs prove problematic: +- Feature is purely additive, can be deprecated without breaking existing workflows +- Remove ADR parsing from CLI commands +- Archive `adrs/` directory +- Update docs to mark as deprecated + +## Open Questions + +1. **Should ADRs have status fields** (proposed, accepted, deprecated, superseded)? + - Leaning NO for v1: Keep simple, use REMOVED/ADDED for superseding + - Can add in future if needed + +2. **Should we support ADR numbering** (ADR-001, ADR-002)? + - Leaning NO: Directory name is sufficient, numbering adds complexity + - Users can number manually if desired (001-database-choice/) + +3. **Should there be a separate archive for ADRs**? + - Leaning NO: Use same `changes/archive/` for both specs and ADRs + - Keeps change history unified + +4. **Should ADRs be required for certain types of spec changes**? + - Leaning NO for v1: Make optional, encourage through documentation + - Could add validation warning in future ("Consider creating ADR for new infrastructure") diff --git a/openspec/changes/add-architectural-decision-records/proposal.md b/openspec/changes/add-architectural-decision-records/proposal.md new file mode 100644 index 000000000..2f3ef51df --- /dev/null +++ b/openspec/changes/add-architectural-decision-records/proposal.md @@ -0,0 +1,154 @@ +# Change: Add Architectural Decision Records (ADRs) + +## Why + +OpenSpec currently supports functional specifications (specs) that document WHAT the system does, but lacks a structured way to document non-functional architectural decisions such as technology choices, infrastructure patterns, library selections, and cross-cutting design decisions. + +**Key problem**: Architectural decisions are inherently **cross-cutting** - they apply to multiple specs simultaneously. For example: +- "Use DynamoDB for all non-SQL use cases" affects every spec that needs data storage +- "Use JWT for authentication" influences all specs dealing with user sessions +- "Deploy on AWS Lambda" impacts how all features are implemented and tested + +Without ADRs, teams must: +- Repeatedly specify the same architectural context across multiple spec changes +- Risk inconsistency when different specs make conflicting technology choices +- Lack a single source of truth for architectural decisions that span capabilities +- Force AI agents to infer or re-specify architectural constraints for each proposal + +ADRs solve this by providing **one-to-many** documentation: one architectural decision influences many functional specifications. + +## What Changes + +This change adds a parallel ADR system alongside specs: + +- **New ADR Structure**: `openspec/adrs/` directory at the **same level** as `specs/` (not nested within specs, because ADRs are cross-cutting) +- **ADR Change Workflow**: ADRs can be proposed, reviewed, and archived using the same delta-based change process as specs +- **Template Support**: Project-configurable templates for ADRs (and optionally specs) via `openspec/templates/` directory +- **CLI Integration**: All existing commands (`list`, `show`, `validate`, `archive`) support ADRs +- **AI Context Integration**: ADRs automatically included in AI agent context to influence proposals, tasks, and designs +- **Proactive ADR Creation**: AI agents automatically detect when architectural decisions are needed and create ADRs without explicit user request +- **Clear Separation**: + - **Specs** = functional behavior (WHAT) - typically one capability, one spec + - **ADRs** = architectural decisions (HOW/WITH WHAT) - **one ADR affects many specs** + - ADRs explicitly declare their scope (which specs they influence) + +### Specific Additions + +1. **Directory Structure**: + - `openspec/adrs/[decision-name]/decision.md` - Concise decision summary (always in AI context) + - `openspec/adrs/[decision-name]/adr.md` - Full rationale and analysis (reference/on-demand) + - `openspec/templates/adr.md` - Optional project-specific ADR template + - `openspec/templates/decision.md` - Optional project-specific decision summary template + - `openspec/changes/[name]/adrs/[decision-name]/` - Proposed ADR changes (both files) + +2. **CLI Commands**: + - `openspec list --adrs` - List all ADRs + - `openspec show [adr-name] --type adr` - Show decision summary (decision.md) + - `openspec show [adr-name] --type adr --full` - Show full ADR with rationale (adr.md) + - `openspec validate [change] --strict` - Validates ADR deltas in changes + - `openspec archive [change]` - Archives ADR changes to `adrs/` (both files) + +3. **Template System**: + - Default ADR template built into CLI + - Project override via `openspec/templates/adr.md` + - Template configuration in `openspec/config.yaml` + +4. **Two-File ADR Structure** (optimized for context efficiency): + + **decision.md** - Concise summary (~200 tokens, always in AI context): + ```markdown + # Decision: [Name] + + **Status:** Accepted | Proposed | Superseded + + **Scope:** [Pattern-based description of what this affects] + + **What:** [One-sentence decision summary] + + **Key Trade-offs:** + - ✓ [Major benefits] + - ✗ [Major drawbacks] + + **See:** [Full ADR](./adr.md) for detailed rationale. + ``` + + **adr.md** - Full analysis (~800-1500 tokens, loaded on-demand): + ```markdown + # ADR: [Name] + + ## Context + [Detailed background, problem statement, constraints] + + ## Options Considered + [Detailed alternatives with comprehensive pros/cons] + + ## Consequences + [Detailed impacts, migration considerations, etc.] + + ## References + [Related specs, ADRs, external resources] + ``` + + **Context Efficiency:** 20 ADRs × ~200 tokens = ~4K tokens (vs ~20K for full ADRs) + +5. **Proactive ADR Detection**: AI agents automatically identify when architectural decisions are needed + + **Example workflow:** + ``` + User: "Create a login feature with session storage" + + AI detects: + - "Login feature" → Functional spec needed + - "Session storage" → Architectural decision (database choice) + + AI checks: + - Is there an ADR for data storage? No → Create one + + AI creates change with BOTH: + ├── adrs/database-strategy/ # NEW ADR for database choice + │ ├── decision.md + │ └── adr.md + └── specs/user-auth/ # Spec references the ADR + └── spec.md + ``` + + **Detection heuristics** (AI creates ADR when decision involves): + - Technology/library selection (database, framework, auth method) + - Infrastructure choices (hosting, deployment, CI/CD platform) + - Security approaches (encryption, authentication strategy) + - Cross-cutting patterns (logging, monitoring, error handling) + - Decisions affecting multiple specs (current or future) + +## Impact + +### Affected Specs +- **openspec-conventions**: Add ADR concepts, structure, and format requirements +- **cli-list**: Extend to support `--adrs` flag +- **cli-show**: Support ADR display with `--type adr` +- **cli-validate**: Validate ADR deltas in changes +- **cli-archive**: Apply ADR deltas to `adrs/` directory +- **change-creation**: Document how to create ADR changes and extract architectural decisions from user requests +- **instruction-loader**: Include ADRs in AI agent context and proactively suggest ADR creation +- **cli-config**: Support template configuration +- **docs-agent-instructions**: Add guidance for when and how to create ADRs proactively +- **NEW: adr-management** - New spec for ADR-specific requirements + +### Affected Code +- `src/cli/list.ts` - Add ADR listing support +- `src/cli/show.ts` - Add ADR display support +- `src/cli/validate.ts` - Add ADR validation +- `src/cli/archive.ts` - Add ADR archiving logic +- `src/core/parsers/` - New ADR parser (similar to spec parser) +- `src/core/init/` - Include ADR directories and templates in init +- `src/core/templates/` - New template management system +- `openspec/AGENTS.md` - Update instructions for ADR workflow + +### Breaking Changes +None. This is purely additive. Existing spec workflows remain unchanged. + +### Migration Path +Projects can gradually adopt ADRs: +1. No action required for existing projects +2. Run `openspec update` to get new template directories (optional) +3. Create first ADR using a change proposal +4. Templates are optional - default template always available diff --git a/openspec/changes/add-architectural-decision-records/specs/adr-management/spec.md b/openspec/changes/add-architectural-decision-records/specs/adr-management/spec.md new file mode 100644 index 000000000..df0ebadf9 --- /dev/null +++ b/openspec/changes/add-architectural-decision-records/specs/adr-management/spec.md @@ -0,0 +1,283 @@ +## ADDED Requirements + +### Requirement: ADR Directory Structure + +The system SHALL maintain a dedicated directory structure for Architectural Decision Records (ADRs) parallel to functional specifications, using a two-file approach for context efficiency. + +#### Scenario: Initializing ADR structure + +- **WHEN** an OpenSpec project is initialized or updated +- **THEN** it SHALL include an `openspec/adrs/` directory +- **AND** each ADR SHALL be stored in `openspec/adrs/[decision-name]/` with two files: + - `decision.md` - Concise summary (always loaded into AI context) + - `adr.md` - Full rationale and analysis (loaded on-demand) +- **AND** the directory structure SHALL mirror the pattern used for specs + +#### Scenario: Organizing ADRs by decision domain + +- **WHEN** creating a new ADR +- **THEN** the decision name SHALL use kebab-case (e.g., `database-selection`, `api-framework-choice`) +- **AND** the name SHALL be descriptive of the architectural decision +- **AND** each ADR SHALL reside in its own directory under `adrs/` +- **AND** contain both `decision.md` and `adr.md` files + +#### Scenario: Two-file structure for context efficiency + +- **WHEN** an ADR is created +- **THEN** it SHALL have two files: + - `decision.md`: Concise summary (~200 tokens) with status, scope, what, and key trade-offs + - `adr.md`: Full context, options analysis, and detailed consequences (~800-1500 tokens) +- **AND** AI agents SHALL primarily load decision.md files for context +- **AND** AI agents MAY load adr.md for detailed analysis when needed + +### Requirement: ADR Document Format + +ADRs SHALL follow a two-file structured format optimized for context efficiency while maintaining comprehensive rationale. + +#### Scenario: Creating decision.md summary file + +- **WHEN** writing a decision.md file +- **THEN** it SHALL include these sections: + - `# Decision: [Name]` - Title + - `**Status:**` - Accepted | Proposed | Superseded + - `**Scope:**` - Pattern-based description of what this affects (not exhaustive list) + - `**What:**` - One-sentence summary of the decision + - `**Key Trade-offs:**` - Major benefits (✓) and drawbacks (✗) + - `**See:**` - Reference to full ADR (./adr.md) +- **AND** keep the file concise (~200 tokens) + +#### Scenario: Creating adr.md rationale file + +- **WHEN** writing an adr.md file +- **THEN** it SHALL include these sections: + - `# ADR: [Decision Name]` - Title + - `## Context` - Detailed background and problem statement + - `## Options Considered` - Comprehensive alternatives analysis with pros/cons + - `## Decision Rationale` - Detailed explanation of why option was chosen + - `## Consequences` - Detailed impacts and migration considerations + - `## References` (optional) - Related specs, ADRs, or external links + +#### Scenario: Pattern-based scope in decision.md + +- **WHEN** writing the Scope field in decision.md +- **THEN** use pattern-based descriptions rather than exhaustive lists: + - Example: "All capabilities requiring non-relational data storage" + - Example: "Authentication and authorization domain" + - Example: "Any spec that needs key-value storage or high-throughput writes" +- **AND** MAY include examples of affected specs for clarity +- **AND** SHALL NOT require maintaining exhaustive lists that need updates when new specs are added + +#### Scenario: Cross-cutting architectural decision in decision.md + +- **WHEN** an ADR applies to multiple specs (e.g., "Use DynamoDB for non-SQL storage") +- **THEN** decision.md SHALL include: + - **Scope:** "All capabilities requiring non-relational data storage" + - Examples in scope description: "user-auth (sessions), analytics-events, audit-logs" +- **AND** each affected spec's design.md SHALL reference this ADR +- **AND** the ADR serves as the single source of truth for this architectural choice + +#### Scenario: Documenting detailed context in adr.md + +- **WHEN** writing the Context section in adr.md +- **THEN** it SHALL provide detailed background explaining the problem +- **AND** it SHALL document all relevant constraints and requirements +- **AND** it SHALL explain why a decision is needed +- **AND** it MAY include stakeholder considerations + +#### Scenario: Comprehensive options analysis in adr.md + +- **WHEN** documenting options considered in adr.md +- **THEN** each option SHALL be listed as a subsection +- **AND** each option SHALL include comprehensive pros and cons +- **AND** each option MAY include cost analysis, performance characteristics, etc. +- **AND** the rationale for rejection/acceptance SHALL be clear and detailed + +#### Scenario: Recording detailed consequences in adr.md + +- **WHEN** documenting consequences in adr.md +- **THEN** both positive and negative impacts SHALL be listed in detail +- **AND** trade-offs accepted SHALL be explicit +- **AND** migration considerations SHALL be documented +- **AND** future considerations and rollback strategies SHALL be noted if relevant + +### Requirement: ADR Template System + +The system SHALL support customizable templates for both decision.md and adr.md files at project level. + +#### Scenario: Using default templates + +- **WHEN** no custom templates are configured +- **THEN** the system SHALL use built-in default templates for both files: + - `src/core/templates/decision.md` - Decision summary template + - `src/core/templates/adr.md` - Full rationale template +- **AND** the default templates SHALL include all standard sections +- **AND** the templates SHALL include helpful placeholder text + +#### Scenario: Configuring project-specific templates + +- **WHEN** a project wants to customize the ADR format +- **THEN** they MAY create `openspec/templates/decision.md` and/or `openspec/templates/adr.md` +- **AND** optionally configure paths in `openspec/config.yaml` under `templates.decision` and `templates.adr` +- **AND** the custom templates SHALL override the built-in defaults + +#### Scenario: Template resolution order + +- **WHEN** the system needs an ADR template +- **THEN** for decision.md it SHALL check in this order: + 1. Project template: `openspec/templates/decision.md` + 2. Built-in default: `src/core/templates/decision.md` +- **AND** for adr.md it SHALL check in this order: + 1. Project template: `openspec/templates/adr.md` + 2. Built-in default: `src/core/templates/adr.md` +- **AND** use the first template found for each file type + +### Requirement: ADR Change Proposals + +ADR changes SHALL follow the same delta-based proposal workflow as functional specifications. + +#### Scenario: Creating ADR change proposal + +- **WHEN** proposing a new or modified ADR +- **THEN** create a change directory under `openspec/changes/[change-name]/` +- **AND** include ADR deltas in `openspec/changes/[change-name]/adrs/[decision-name]/` with both files: + - `decision.md` - Summary with delta operations + - `adr.md` - Full rationale with delta operations +- **AND** use delta operations: `## ADDED Decisions`, `## MODIFIED Decisions`, `## REMOVED Decisions`, `## RENAMED Decisions` + +#### Scenario: Adding new ADR + +- **WHEN** creating a new architectural decision +- **THEN** create both files in `changes/[name]/adrs/[decision-name]/`: + - `decision.md` with `## ADDED Decisions` section containing summary + - `adr.md` with `## ADDED Decisions` section containing full rationale +- **AND** include the complete content in both files +- **AND** follow the standard two-file ADR format + +#### Scenario: Modifying existing ADR + +- **WHEN** updating an existing architectural decision +- **THEN** include changes in both files under `## MODIFIED Decisions`: + - Update `decision.md` if summary, scope, or trade-offs change + - Update `adr.md` if context, options, or detailed consequences change +- **AND** use the same decision name header as in current ADR +- **AND** include the complete updated content for modified files +- **AND** optionally annotate what changed with inline comments + +#### Scenario: Removing obsolete ADR + +- **WHEN** deprecating an architectural decision +- **THEN** list it under `## REMOVED Decisions` +- **AND** include the decision name for identification +- **AND** document the reason for removal +- **AND** reference any superseding ADR if applicable + +#### Scenario: Renaming ADR + +- **WHEN** changing an ADR's name +- **THEN** use `## RENAMED Decisions` section +- **AND** specify FROM and TO names explicitly +- **AND** if content also changes, include in `## MODIFIED Decisions` using the new name + +### Requirement: Decision-Level Granularity + +ADR deltas SHALL operate at the decision level, treating each ADR file as an atomic unit. + +#### Scenario: Matching decisions for updates + +- **WHEN** processing ADR deltas +- **THEN** match decisions by the `# ADR: [Name]` header +- **AND** use normalized header matching (trim whitespace) +- **AND** compare headers with case-sensitive equality after normalization + +#### Scenario: Validating delta references + +- **WHEN** validating ADR changes +- **THEN** ensure MODIFIED decisions reference existing ADRs +- **AND** ensure REMOVED decisions reference existing ADRs +- **AND** ensure ADDED decisions don't conflict with existing ADRs +- **AND** report specific errors for mismatches + +### Requirement: ADR and Spec Relationship + +ADRs SHALL be clearly distinguished from functional specifications with different purposes, structures, and scope characteristics. ADRs are inherently cross-cutting and apply to multiple specs. + +#### Scenario: One-to-many relationship between ADRs and specs + +- **WHEN** an architectural decision affects multiple capabilities +- **THEN** create one ADR that applies to all affected specs (not separate ADRs per spec) +- **AND** list all affected specs in the ADR's Scope section +- **AND** each affected spec references the same ADR +- **AND** this ensures consistency - one source of truth for cross-cutting decisions + +#### Scenario: Determining when to use ADR vs Spec + +- **WHEN** documenting a decision +- **THEN** use ADR for architectural and non-functional decisions that typically affect multiple specs: + - Technology choices (frameworks, libraries, languages) + - Infrastructure patterns (deployment, hosting, CI/CD) + - Security approaches (authentication methods, encryption) + - Cross-cutting concerns (logging, monitoring, error handling) + - Data storage strategies (database selection, caching approaches) +- **AND** use Spec for functional behavioral requirements focused on a single capability: + - Features and capabilities + - User-facing behavior + - API contracts + - Business logic rules + +#### Scenario: Referencing ADRs from Specs + +- **WHEN** a spec depends on architectural decisions +- **THEN** reference relevant ADRs in the spec's design.md +- **AND** use format: "See ADR: [decision-name]" for references +- **AND** ensure spec implementation aligns with ADR decisions + +#### Scenario: Referencing Specs from ADRs + +- **WHEN** an ADR affects multiple specs +- **THEN** list affected specs in the ADR's References section +- **AND** explain how the decision impacts each spec +- **AND** update affected specs' design.md to reference the ADR + +### Requirement: AI Context Integration + +ADRs SHALL be included in AI agent context to influence proposal generation and implementation decisions. + +#### Scenario: Loading ADRs for AI context + +- **WHEN** an AI agent is creating a proposal or implementation +- **THEN** the system SHALL load relevant ADRs +- **AND** include ADRs in the context provided to the AI +- **AND** AI agents SHALL reference ADRs when making architectural decisions + +#### Scenario: AI proposal consistency with ADRs + +- **WHEN** an AI creates a proposal involving architectural choices +- **THEN** the proposal's design.md SHALL reference relevant ADRs +- **AND** implementation tasks SHALL align with ADR decisions +- **AND** conflicts with existing ADRs SHALL be flagged or explained + +### Requirement: ADR Lifecycle + +ADRs SHALL follow a lifecycle from proposal to acceptance to potential deprecation. + +#### Scenario: Proposing new ADR + +- **WHEN** creating an ADR proposal +- **THEN** include it in a change proposal for review +- **AND** validate the ADR format +- **AND** await approval before archiving to `adrs/` + +#### Scenario: Accepting ADR + +- **WHEN** an ADR change is approved and implemented +- **THEN** archive the change to move ADR to `openspec/adrs/` +- **AND** the ADR becomes active guidance for future work +- **AND** update AGENTS.md if the ADR affects AI workflows + +#### Scenario: Superseding ADR + +- **WHEN** an ADR is no longer valid +- **THEN** create a new change with the superseding ADR under `## ADDED Decisions` +- **AND** remove the old ADR under `## REMOVED Decisions` +- **AND** reference the superseding ADR in the removal reason +- **AND** archive both changes together when complete diff --git a/openspec/changes/add-architectural-decision-records/specs/change-creation/spec.md b/openspec/changes/add-architectural-decision-records/specs/change-creation/spec.md new file mode 100644 index 000000000..18f5db60b --- /dev/null +++ b/openspec/changes/add-architectural-decision-records/specs/change-creation/spec.md @@ -0,0 +1,134 @@ +## ADDED Requirements + +### Requirement: Creating ADR Changes + +Change proposals SHALL support creating and modifying Architectural Decision Records (ADRs) using the delta-based approach. + +#### Scenario: Creating change with ADR deltas + +- **WHEN** creating a change proposal that includes architectural decisions +- **THEN** create ADR delta files under `openspec/changes/[change-name]/adrs/[decision-name]/adr.md` +- **AND** use delta sections: `## ADDED Decisions`, `## MODIFIED Decisions`, `## REMOVED Decisions`, `## RENAMED Decisions` +- **AND** follow the same delta pattern as spec changes + +#### Scenario: Scaffolding new ADR in a change + +- **WHEN** adding a new architectural decision in a change +- **THEN** create directory `changes/[change-name]/adrs/[decision-name]/` +- **AND** create both files: + - `decision.md` with `## ADDED Decisions` section and summary + - `adr.md` with `## ADDED Decisions` section and full rationale +- **AND** include complete content in both files following required formats +- **AND** follow the project's templates if available + +#### Scenario: Modifying existing ADR in a change + +- **WHEN** updating an existing architectural decision +- **THEN** reference the existing ADR by name under `## MODIFIED Decisions` +- **AND** include the complete updated ADR content +- **AND** use the same decision name header as in current ADR +- **AND** optionally annotate changes with inline comments for reviewers + +#### Scenario: Removing ADR in a change + +- **WHEN** deprecating an architectural decision +- **THEN** list it under `## REMOVED Decisions` +- **AND** include the decision name for identification +- **AND** document the reason for removal +- **AND** reference any superseding ADR if the decision is being replaced + +#### Scenario: Combining spec and ADR changes + +- **WHEN** a change affects both functional specs and architectural decisions +- **THEN** include both spec deltas in `changes/[change-name]/specs/` +- **AND** include ADR deltas in `changes/[change-name]/adrs/` +- **AND** reference ADRs from relevant spec design.md files +- **AND** explain in proposal.md how specs and ADRs relate + +#### Scenario: Referencing ADRs in design.md + +- **WHEN** a change's implementation depends on architectural decisions +- **THEN** reference relevant ADRs in the change's `design.md` +- **AND** use format: "See ADR: [decision-name]" +- **AND** explain how the ADR influences the implementation approach + +### Requirement: Extracting Architectural Decisions from Requests + +AI agents SHALL proactively identify when user requests contain architectural decisions and create ADRs automatically. + +#### Scenario: Identifying architectural decisions in feature requests + +- **WHEN** AI processes a user request for a new feature +- **THEN** analyze the request for architectural implications: + - Technology choices (e.g., "session storage" implies database selection) + - Infrastructure needs (e.g., "real-time updates" implies WebSocket/SSE decision) + - Security requirements (e.g., "user authentication" implies auth method decision) + - Cross-cutting concerns (e.g., "track events" implies logging/analytics strategy) +- **AND** identify decisions that should be ADRs vs spec implementation details + +#### Scenario: Creating ADR and spec in same change + +- **WHEN** AI detects an architectural decision is needed for a spec +- **THEN** create both in the same change: + - ADR under `changes/[name]/adrs/[decision]/` + - Spec under `changes/[name]/specs/[capability]/` +- **AND** explain in proposal.md: "This feature requires [architectural decision], so including ADR" +- **AND** structure tasks.md with dependency: ADR review → spec implementation +- **AND** have spec's design.md reference the ADR + +#### Scenario: Example - login feature with storage + +- **WHEN** user requests "create a login feature with session storage" +- **THEN** AI SHALL detect: + - Functional requirement: login feature (spec) + - Architectural decision: database for sessions (ADR) +- **AND** check: does an ADR for data storage exist? + - If YES: reference existing ADR in spec + - If NO: create new ADR in same change +- **AND** create change containing both ADR and spec + +#### Scenario: Reusing existing ADRs + +- **WHEN** AI detects an architectural decision is needed +- **THEN** check if a relevant ADR already exists +- **AND** if ADR exists and applies, reference it from the spec +- **AND** if ADR exists but needs updating, modify it in the change +- **AND** only create new ADR if no relevant one exists + +#### Scenario: Determining ADR vs implementation detail + +- **WHEN** deciding whether a decision warrants an ADR +- **THEN** create ADR if the decision: + - Affects or could affect multiple specs + - Involves technology/infrastructure selection + - Has multiple reasonable alternatives + - Has long-term architectural implications +- **AND** keep as implementation detail if the decision: + - Only affects one capability + - Is purely functional/behavioral + - Is a standard implementation pattern + - Unlikely to be reused elsewhere + +### Requirement: ADR Template Usage + +When creating new ADRs, the system SHALL support using templates to ensure consistency. + +#### Scenario: Using default ADR template + +- **WHEN** scaffolding a new ADR and no custom template exists +- **THEN** use the built-in default ADR template +- **AND** populate placeholders with example content +- **AND** include all standard sections + +#### Scenario: Using custom ADR template + +- **WHEN** scaffolding a new ADR and `openspec/templates/adr.md` exists +- **THEN** use the custom template instead of the default +- **AND** respect project-specific sections and formatting +- **AND** preserve template placeholders for author to fill in + +#### Scenario: Manual ADR creation without template + +- **WHEN** an author creates an ADR manually without scaffolding +- **THEN** validation SHALL still check for required sections +- **AND** the ADR SHALL follow the standard format regardless of template diff --git a/openspec/changes/add-architectural-decision-records/specs/cli-archive/spec.md b/openspec/changes/add-architectural-decision-records/specs/cli-archive/spec.md new file mode 100644 index 000000000..302bb2000 --- /dev/null +++ b/openspec/changes/add-architectural-decision-records/specs/cli-archive/spec.md @@ -0,0 +1,90 @@ +## ADDED Requirements + +### Requirement: Archive ADR Changes + +The `openspec archive` command SHALL apply ADR deltas from change proposals to the `openspec/adrs/` directory using the same delta-based approach as specs. + +#### Scenario: Archiving change with ADR deltas + +- **WHEN** running `openspec archive [change-name]` +- **THEN** the command SHALL process ADR deltas in `changes/[change-name]/adrs/` +- **AND** apply delta operations to `openspec/adrs/` directory +- **AND** process in order: RENAMED → REMOVED → MODIFIED → ADDED +- **AND** update both specs and ADRs atomically + +#### Scenario: Processing ADDED ADR decisions + +- **WHEN** archiving a change with `## ADDED Decisions` +- **THEN** the command SHALL create new ADR directory under `openspec/adrs/[decision-name]/` +- **AND** copy both files from the delta: + - `decision.md` - Decision summary + - `adr.md` - Full rationale +- **AND** validate that the decision doesn't already exist +- **AND** report errors if conflicts are detected + +#### Scenario: Processing MODIFIED ADR decisions + +- **WHEN** archiving a change with `## MODIFIED Decisions` +- **THEN** the command SHALL locate the existing ADR by header matching +- **AND** update the modified file(s): + - Replace `decision.md` if present in delta + - Replace `adr.md` if present in delta + - Preserve files not included in delta +- **AND** preserve the directory structure +- **AND** report errors if the referenced decision doesn't exist + +#### Scenario: Processing REMOVED ADR decisions + +- **WHEN** archiving a change with `## REMOVED Decisions` +- **THEN** the command SHALL delete the entire ADR directory (both files) +- **AND** validate that the decision exists before removal +- **AND** report errors if the decision doesn't exist +- **AND** log the removal reason for audit purposes + +#### Scenario: Processing RENAMED ADR decisions + +- **WHEN** archiving a change with `## RENAMED Decisions` +- **THEN** the command SHALL rename the ADR directory from old to new name +- **AND** update the headers in both files to match new name: + - `# Decision:` in decision.md + - `# ADR:` in adr.md +- **AND** validate that FROM decision exists and TO decision doesn't +- **AND** process renames before other operations to avoid conflicts + +#### Scenario: Combined spec and ADR archiving + +- **WHEN** archiving a change with both spec and ADR deltas +- **THEN** the command SHALL apply both sets of deltas +- **AND** validate both specs and ADRs before applying changes +- **AND** apply changes atomically (all or nothing) +- **AND** roll back all changes if any delta application fails + +#### Scenario: Skip ADR archiving + +- **WHEN** running `openspec archive [change-name] --skip-adrs` +- **THEN** the command SHALL archive only spec deltas +- **AND** move the change to archive without applying ADR deltas +- **AND** leave ADR deltas in the archived change for future reference + +#### Scenario: ADR archiving conflicts + +- **WHEN** ADR delta operations conflict with current state +- **THEN** the command SHALL detect conflicts before applying changes +- **AND** report specific conflict details (which decision, what conflict) +- **AND** require manual resolution before proceeding +- **AND** provide guidance on resolving conflicts + +#### Scenario: Archive with no ADR deltas + +- **WHEN** archiving a change with no ADR deltas +- **THEN** the command SHALL skip ADR processing +- **AND** archive only spec deltas if present +- **AND** move the change to archive normally + +#### Scenario: Validate before archive + +- **WHEN** running `openspec archive [change-name]` +- **THEN** the command SHALL validate all ADR deltas before applying +- **AND** check for structural correctness, conflicts, and missing references +- **AND** abort archiving if validation fails +- **AND** display validation errors clearly diff --git a/openspec/changes/add-architectural-decision-records/specs/cli-config/spec.md b/openspec/changes/add-architectural-decision-records/specs/cli-config/spec.md new file mode 100644 index 000000000..14f525f47 --- /dev/null +++ b/openspec/changes/add-architectural-decision-records/specs/cli-config/spec.md @@ -0,0 +1,52 @@ +## ADDED Requirements + +### Requirement: ADR Template Configuration + +The `openspec/config.yaml` SHALL support configuring custom templates for both decision.md and adr.md files. + +#### Scenario: Configuring custom ADR template paths + +- **WHEN** a project wants to use custom ADR templates +- **THEN** add template configuration to `openspec/config.yaml`: + ```yaml + templates: + decision: ./templates/decision.md # Optional + adr: ./templates/adr.md # Optional + ``` +- **AND** the specified paths SHALL be relative to the openspec directory +- **AND** the system SHALL use these templates when scaffolding new ADRs + +#### Scenario: Template resolution with configuration + +- **WHEN** the system needs ADR templates +- **THEN** for decision.md it SHALL resolve in this order: + 1. Check `config.yaml` for `templates.decision` path + 2. Check for `openspec/templates/decision.md` (default location) + 3. Use built-in default template +- **AND** for adr.md it SHALL resolve in this order: + 1. Check `config.yaml` for `templates.adr` path + 2. Check for `openspec/templates/adr.md` (default location) + 3. Use built-in default template +- **AND** use the first template found for each file type + +#### Scenario: Invalid template path in configuration + +- **WHEN** `config.yaml` specifies a template path that doesn't exist +- **THEN** the system SHALL display a warning +- **AND** fall back to checking default template location +- **AND** ultimately use built-in default if no valid template found + +#### Scenario: Validating template configuration + +- **WHEN** running `openspec validate --config` +- **THEN** the command SHALL check if configured template paths exist +- **AND** warn about missing or inaccessible template files +- **AND** suggest corrections for invalid paths + +#### Scenario: Template configuration for future extensibility + +- **WHEN** template configuration is added +- **THEN** it SHALL use a `templates` section in config.yaml +- **AND** support both `decision` and `adr` template types +- **AND** support future template types (e.g., `spec`, `proposal`, `design`) +- **AND** maintain backward compatibility if templates section is absent diff --git a/openspec/changes/add-architectural-decision-records/specs/cli-list/spec.md b/openspec/changes/add-architectural-decision-records/specs/cli-list/spec.md new file mode 100644 index 000000000..12a32871f --- /dev/null +++ b/openspec/changes/add-architectural-decision-records/specs/cli-list/spec.md @@ -0,0 +1,39 @@ +## ADDED Requirements + +### Requirement: List ADRs + +The `openspec list` command SHALL support listing Architectural Decision Records (ADRs) alongside changes and specs. + +#### Scenario: Listing all ADRs + +- **WHEN** running `openspec list --adrs` +- **THEN** the command SHALL display all ADRs in the `openspec/adrs/` directory +- **AND** show the decision name for each ADR +- **AND** format the output in a readable table or list format + +#### Scenario: Listing ADRs with details + +- **WHEN** running `openspec list --adrs --long` +- **THEN** the command SHALL display ADRs with additional details +- **AND** include the ADR title from the `# ADR:` header +- **AND** optionally show a brief summary or first line of context + +#### Scenario: Combined listing of specs and ADRs + +- **WHEN** running `openspec list --specs --adrs` +- **THEN** the command SHALL display both specs and ADRs +- **AND** clearly distinguish between specs and ADRs (e.g., with prefixes or separate sections) +- **AND** maintain separate counts for specs and ADRs + +#### Scenario: JSON output for ADRs + +- **WHEN** running `openspec list --adrs --json` +- **THEN** the command SHALL output ADRs in JSON format +- **AND** include fields: `name`, `path`, `title` +- **AND** the output SHALL be parseable for scripting + +#### Scenario: No ADRs exist + +- **WHEN** running `openspec list --adrs` and no ADRs exist +- **THEN** the command SHALL display a message indicating no ADRs found +- **AND** exit with status code 0 (success) diff --git a/openspec/changes/add-architectural-decision-records/specs/cli-show/spec.md b/openspec/changes/add-architectural-decision-records/specs/cli-show/spec.md new file mode 100644 index 000000000..3819eceae --- /dev/null +++ b/openspec/changes/add-architectural-decision-records/specs/cli-show/spec.md @@ -0,0 +1,47 @@ +## ADDED Requirements + +### Requirement: Show ADR Details + +The `openspec show` command SHALL support displaying Architectural Decision Records (ADRs) with options for summary or full detail. + +#### Scenario: Showing ADR summary by default + +- **WHEN** running `openspec show [decision-name] --type adr` +- **THEN** the command SHALL display the decision.md file (concise summary) +- **AND** include: Status, Scope, What, Key Trade-offs, and reference to full ADR +- **AND** format the output for readability in the terminal + +#### Scenario: Showing full ADR with rationale + +- **WHEN** running `openspec show [decision-name] --type adr --full` +- **THEN** the command SHALL display the adr.md file (full rationale) +- **AND** include all sections: Context, Options Considered, Decision Rationale, Consequences, References +- **AND** format the output for readability in the terminal + +#### Scenario: Auto-detecting ADR vs spec + +- **WHEN** running `openspec show [name]` without --type flag +- **THEN** the command SHALL check both `specs/` and `adrs/` directories +- **AND** if the name exists in only one location, display that item +- **AND** if the name exists in both locations, prompt user to disambiguate or suggest using `--type` + +#### Scenario: Showing ADR with JSON output + +- **WHEN** running `openspec show [decision-name] --type adr --json` +- **THEN** the command SHALL output the ADR in JSON format +- **AND** include fields: `name`, `path`, `content`, `sections` +- **AND** parse sections into structured JSON if possible + +#### Scenario: ADR not found + +- **WHEN** running `openspec show [decision-name] --type adr` and the ADR doesn't exist +- **THEN** the command SHALL display an error message +- **AND** suggest similar ADR names if any exist +- **AND** exit with status code 1 (error) + +#### Scenario: Showing ADR delta in a change + +- **WHEN** running `openspec show [change-name] --json --deltas-only` +- **THEN** the command SHALL include ADR deltas alongside spec deltas +- **AND** distinguish ADR deltas from spec deltas in the output +- **AND** show ADDED, MODIFIED, REMOVED, and RENAMED decisions diff --git a/openspec/changes/add-architectural-decision-records/specs/cli-validate/spec.md b/openspec/changes/add-architectural-decision-records/specs/cli-validate/spec.md new file mode 100644 index 000000000..30ab103b0 --- /dev/null +++ b/openspec/changes/add-architectural-decision-records/specs/cli-validate/spec.md @@ -0,0 +1,70 @@ +## ADDED Requirements + +### Requirement: Validate ADR Changes + +The `openspec validate` command SHALL validate Architectural Decision Records (ADRs) in change proposals alongside spec validation. + +#### Scenario: Validating ADR deltas in a change + +- **WHEN** running `openspec validate [change-name] --strict` +- **THEN** the command SHALL validate all ADR deltas in `changes/[change-name]/adrs/` +- **AND** check that ADR deltas use correct section headers (`## ADDED Decisions`, etc.) +- **AND** validate that each delta operation references valid decisions +- **AND** report any validation errors with clear messages + +#### Scenario: Validating ADR format + +- **WHEN** validating an ADR delta +- **THEN** the command SHALL check for required sections: Context, Decision, Options Considered, Consequences +- **AND** warn if optional sections (References) are missing but don't fail validation +- **AND** validate that the ADR title follows format `# ADR: [Name]` + +#### Scenario: Validating ADDED decisions + +- **WHEN** validating `## ADDED Decisions` in an ADR delta +- **THEN** the command SHALL verify that the decision doesn't already exist in `openspec/adrs/` +- **AND** check that the ADR includes all required sections +- **AND** report errors if the decision name conflicts with existing ADRs + +#### Scenario: Validating MODIFIED decisions + +- **WHEN** validating `## MODIFIED Decisions` in an ADR delta +- **THEN** the command SHALL verify that the referenced decision exists in current ADRs +- **AND** check that the ADR header matches an existing decision (normalized) +- **AND** report errors if the decision doesn't exist + +#### Scenario: Validating REMOVED decisions + +- **WHEN** validating `## REMOVED Decisions` in an ADR delta +- **THEN** the command SHALL verify that the referenced decision exists in current ADRs +- **AND** check that a removal reason is provided +- **AND** report errors if the decision doesn't exist + +#### Scenario: Validating RENAMED decisions + +- **WHEN** validating `## RENAMED Decisions` in an ADR delta +- **THEN** the command SHALL verify that the FROM decision exists +- **AND** verify that the TO decision doesn't already exist +- **AND** check that FROM and TO are both specified +- **AND** report errors for invalid renames + +#### Scenario: Combined spec and ADR validation + +- **WHEN** running `openspec validate [change-name]` +- **THEN** the command SHALL validate both specs and ADRs in the change +- **AND** report validation results separately for specs and ADRs +- **AND** exit with error status if either specs or ADRs have validation errors + +#### Scenario: Validating standalone ADR + +- **WHEN** running `openspec validate [decision-name] --type adr` +- **THEN** the command SHALL validate the ADR file directly in `openspec/adrs/` +- **AND** check for required sections and proper format +- **AND** report any format or structural issues + +#### Scenario: No ADR deltas to validate + +- **WHEN** running `openspec validate [change-name]` and the change has no ADR deltas +- **THEN** the command SHALL not report ADR validation errors +- **AND** only validate spec deltas if present +- **AND** indicate that no ADRs were found in validation output diff --git a/openspec/changes/add-architectural-decision-records/specs/docs-agent-instructions/spec.md b/openspec/changes/add-architectural-decision-records/specs/docs-agent-instructions/spec.md new file mode 100644 index 000000000..10a09725a --- /dev/null +++ b/openspec/changes/add-architectural-decision-records/specs/docs-agent-instructions/spec.md @@ -0,0 +1,101 @@ +## ADDED Requirements + +### Requirement: ADR Creation Guidance in Agent Instructions + +The agent instructions (AGENTS.md) SHALL include comprehensive guidance on when and how to create Architectural Decision Records proactively. + +#### Scenario: Documenting ADR vs spec decision criteria + +- **WHEN** AGENTS.md is updated for ADR support +- **THEN** it SHALL include clear criteria for when to create ADRs: + - Technology/library selection (database, framework, auth method, language) + - Infrastructure decisions (hosting platform, deployment strategy, CI/CD) + - Security approaches (authentication method, encryption strategy) + - Cross-cutting patterns (logging, monitoring, error handling) + - Data storage strategies (database type, caching approach) + - Decisions affecting multiple specs (current or future) +- **AND** include criteria for when NOT to create ADRs: + - Feature-specific implementation details + - Decisions only affecting one capability + - Standard implementation patterns + - Purely functional/behavioral decisions + +#### Scenario: Proactive ADR detection instructions + +- **WHEN** AGENTS.md provides ADR guidance +- **THEN** it SHALL instruct AI agents to: + - Analyze user requests for architectural implications + - Check if relevant ADRs exist before creating specs + - Create ADRs proactively when architectural decisions are detected + - Not require users to explicitly request ADRs + - Include both ADR and spec in the same change when appropriate + +#### Scenario: Example-driven guidance + +- **WHEN** documenting ADR creation in AGENTS.md +- **THEN** include concrete examples: + - Example 1: "add login with session storage" → Create database-strategy ADR + user-auth spec + - Example 2: "add real-time notifications" → Create messaging-strategy ADR + notifications spec + - Example 3: "add user analytics" → Check for existing analytics ADR, create if missing +- **AND** show the resulting change structure with both ADR and spec +- **AND** explain how to reference ADRs from specs + +#### Scenario: ADR workflow integration + +- **WHEN** AGENTS.md documents the change workflow +- **THEN** it SHALL explain: + - How to create a change with both ADRs and specs + - How to structure tasks.md with ADR → spec dependencies + - How to reference existing ADRs from new specs + - How to update existing ADRs when architectural decisions evolve + - How to determine if existing ADR needs modification vs creating new ADR + +#### Scenario: Quick reference for ADR decisions + +- **WHEN** AGENTS.md provides ADR guidance +- **THEN** include a decision tree or checklist: + ``` + Does this request involve: + ☐ Technology selection? (database, framework, library) + ☐ Infrastructure choice? (hosting, deployment, CI/CD) + ☐ Security approach? (auth method, encryption) + ☐ Cross-cutting concern? (logging, monitoring, error handling) + ☐ Decision affecting multiple specs? + + If YES to any → Check for existing ADR + - ADR exists and applies → Reference it + - ADR exists but needs update → Modify it + - No ADR exists → Create new ADR in same change + ``` + +#### Scenario: Pattern-based scope guidance + +- **WHEN** AGENTS.md explains ADR scope documentation +- **THEN** instruct AI agents to: + - Use pattern-based descriptions, not exhaustive lists + - Provide examples: "All capabilities requiring non-relational data storage" + - Include specific examples for clarity: "user-auth (sessions), analytics-events" + - NOT maintain exhaustive lists that require updates + - Update scope patterns when architectural boundaries change + +#### Scenario: Two-file structure usage + +- **WHEN** AGENTS.md documents ADR creation +- **THEN** explain the two-file structure: + - decision.md: Concise summary for quick reference (~200 tokens) + - adr.md: Full rationale for deep analysis (~800-1500 tokens) +- **AND** instruct when to create each: + - Always create both for new ADRs + - Update decision.md when summary/scope/trade-offs change + - Update adr.md when context/options/consequences change + - Both files use same delta operations (ADDED/MODIFIED/REMOVED/RENAMED) + +#### Scenario: CLI command reference for ADRs + +- **WHEN** AGENTS.md provides ADR workflow documentation +- **THEN** include CLI command examples: + - `openspec list --adrs` - List all ADRs + - `openspec show [adr] --type adr` - Show decision summary + - `openspec show [adr] --type adr --full` - Show full rationale + - `openspec validate [change]` - Validate ADRs and specs + - `openspec archive [change]` - Archive both ADRs and specs diff --git a/openspec/changes/add-architectural-decision-records/specs/instruction-loader/spec.md b/openspec/changes/add-architectural-decision-records/specs/instruction-loader/spec.md new file mode 100644 index 000000000..15fecbddd --- /dev/null +++ b/openspec/changes/add-architectural-decision-records/specs/instruction-loader/spec.md @@ -0,0 +1,93 @@ +## ADDED Requirements + +### Requirement: Include ADRs in AI Context + +The instruction loader SHALL include Architectural Decision Records (ADRs) when providing context to AI agents, prioritizing decision summaries for efficiency. + +#### Scenario: Loading ADR summaries for AI context + +- **WHEN** an AI agent requests context about the project +- **THEN** the instruction loader SHALL load decision.md files from all ADRs in `openspec/adrs/` +- **AND** provide decision summaries alongside specs, project.md, and AGENTS.md +- **AND** clearly label ADRs as architectural decisions to distinguish from functional specs +- **AND** keep context efficient (~200 tokens per ADR vs ~1000+ for full ADRs) + +#### Scenario: Loading full ADR on demand + +- **WHEN** an AI agent needs detailed rationale for a specific ADR +- **THEN** the instruction loader MAY load the full adr.md file +- **AND** provide complete context, options analysis, and consequences +- **AND** load only when explicitly needed (e.g., when modifying an ADR or resolving conflicts) + +#### Scenario: Referencing ADRs in proposals + +- **WHEN** an AI agent creates a proposal involving architectural choices +- **THEN** the agent SHALL check relevant ADRs +- **AND** reference applicable ADRs in the proposal's design.md +- **AND** ensure implementation tasks align with ADR decisions +- **AND** flag potential conflicts with existing ADRs + +#### Scenario: ADR-aware implementation + +- **WHEN** an AI agent implements tasks from a change +- **THEN** the agent SHALL consult referenced ADRs +- **AND** follow architectural patterns specified in ADRs +- **AND** use technologies and approaches documented in ADRs +- **AND** avoid contradicting established architectural decisions without explicit justification + +#### Scenario: Proposing ADR updates + +- **WHEN** an AI agent identifies need for new or updated architectural decision +- **THEN** the agent SHALL propose ADR changes using the delta format +- **AND** explain why the architectural decision is needed +- **AND** document alternatives considered +- **AND** outline consequences of the decision + +#### Scenario: Loading specific ADRs by topic + +- **WHEN** an AI agent works on a change affecting specific architectural areas +- **THEN** the instruction loader MAY prioritize loading relevant ADRs +- **AND** include related ADRs based on keywords or references +- **AND** ensure comprehensive context for architectural consistency + +### Requirement: Proactive ADR Suggestion + +The system SHALL guide AI agents to proactively detect when architectural decisions are needed and create ADRs without explicit user request. + +#### Scenario: Detecting architectural decisions in user requests + +- **WHEN** an AI agent receives a request that implies architectural choices +- **THEN** the agent SHALL analyze the request for architectural decisions: + - Technology selection (database, framework, library, language) + - Infrastructure choices (hosting platform, deployment strategy, CI/CD) + - Security approaches (authentication method, encryption strategy) + - Cross-cutting patterns (logging, monitoring, error handling) + - Data storage strategies (database type, caching approach) +- **AND** check if relevant ADRs exist +- **AND** create new ADRs in the same change if architectural decisions are missing + +#### Scenario: Extracting architectural decisions from feature requests + +- **WHEN** user requests a feature like "add login with session storage" +- **THEN** the AI agent SHALL identify implicit architectural decisions: + - "session storage" implies database/storage choice +- **AND** check for existing ADR covering this decision +- **AND** if no ADR exists, create one in the same change as the spec +- **AND** have the spec reference the ADR in its design.md + +#### Scenario: Single change with both ADR and spec + +- **WHEN** AI creates a change with both new ADR and new spec +- **THEN** structure the change with both: + - `changes/[name]/adrs/[decision]/` - Architectural decision + - `changes/[name]/specs/[capability]/` - Functional spec +- **AND** explain in proposal.md why both are needed +- **AND** set up task dependencies: ADR review before spec implementation +- **AND** ensure spec references the ADR + +#### Scenario: Not creating unnecessary ADRs + +- **WHEN** a decision is feature-specific and unlikely to affect other specs +- **THEN** the AI agent SHALL NOT create an ADR +- **AND** document the decision in the spec's design.md instead +- **AND** only elevate to ADR if the decision is truly cross-cutting or architectural diff --git a/openspec/changes/add-architectural-decision-records/specs/openspec-conventions/spec.md b/openspec/changes/add-architectural-decision-records/specs/openspec-conventions/spec.md new file mode 100644 index 000000000..742b17a93 --- /dev/null +++ b/openspec/changes/add-architectural-decision-records/specs/openspec-conventions/spec.md @@ -0,0 +1,179 @@ +## MODIFIED Requirements + +### Requirement: Project Structure + +An OpenSpec project SHALL maintain a consistent directory structure for specifications, architectural decisions, and changes. + +#### Scenario: Initializing project structure + +- **WHEN** an OpenSpec project is initialized +- **THEN** it SHALL have this structure: +``` +openspec/ +├── project.md # Project-specific context +├── AGENTS.md # AI assistant instructions +├── specs/ # Current deployed capabilities (functional) +│ └── [capability]/ # Single, focused capability +│ ├── spec.md # WHAT and WHY +│ └── design.md # HOW (optional, for established patterns) +├── adrs/ # Architectural Decision Records (non-functional) +│ └── [decision-name]/ # Single architectural decision +│ ├── decision.md # Summary: status, scope, what, trade-offs (~200 tokens) +│ └── adr.md # Full rationale: context, options, consequences (~800-1500 tokens) +├── templates/ # Optional custom templates +│ ├── decision.md # Project-specific decision summary template +│ └── adr.md # Project-specific ADR rationale template +└── changes/ # Proposed changes + ├── [change-name]/ # Descriptive change identifier + │ ├── proposal.md # Why, what, and impact + │ ├── tasks.md # Implementation checklist + │ ├── design.md # Technical decisions (optional) + │ ├── specs/ # Spec deltas + │ │ └── [capability]/ + │ │ └── spec.md # ADDED/MODIFIED/REMOVED Requirements + │ └── adrs/ # ADR deltas + │ └── [decision-name]/ + │ ├── decision.md # ADDED/MODIFIED/REMOVED Decisions (summary) + │ └── adr.md # ADDED/MODIFIED/REMOVED Decisions (full) + └── archive/ # Completed changes + └── YYYY-MM-DD-[name]/ +``` + +## ADDED Requirements + +### Requirement: Distinction Between Specs and ADRs + +OpenSpec SHALL maintain a clear distinction between functional specifications (specs) and Architectural Decision Records (ADRs). ADRs are inherently cross-cutting and apply to multiple specs, while specs typically focus on a single capability. + +#### Scenario: Functional specifications for behavior + +- **WHEN** documenting what the system does or how it behaves +- **THEN** use specs in `openspec/specs/[capability]/spec.md` +- **AND** specs SHALL focus on functional requirements, features, and user-facing behavior +- **AND** specs SHALL use the structured format with `### Requirement:` and `#### Scenario:` headers + +#### Scenario: ADRs for architectural decisions + +- **WHEN** documenting architectural or non-functional decisions +- **THEN** use ADRs in `openspec/adrs/[decision-name]/adr.md` +- **AND** ADRs SHALL focus on technology choices, infrastructure, patterns, and cross-cutting concerns +- **AND** ADRs SHALL use the ADR format with Context, Decision, Options, and Consequences sections + +#### Scenario: Cross-cutting ADR example + +- **WHEN** an architectural decision affects multiple specs +- **THEN** create one ADR listing all affected specs in its Scope section +- **AND** each affected spec references the ADR in its design.md +- **AND** the ADR serves as single source of truth +- Example: ADR "Use DynamoDB for Non-SQL Storage" lists scope: "user-auth, sessions, analytics-events, audit-logs" + +#### Scenario: Choosing between spec and ADR + +- **WHEN** deciding where to document information +- **THEN** use this guideline: + - **Specs**: Features, capabilities, user behavior, API contracts, business rules (typically one capability) + - **ADRs**: Technology stack, infrastructure patterns, security approaches, library selections, architectural patterns (typically cross-cutting, affects multiple specs) +- **AND** specs MAY reference ADRs for architectural context +- **AND** ADRs SHALL declare their scope (which specs they affect) + +### Requirement: ADR Template Support + +OpenSpec SHALL support customizable templates for ADRs to accommodate different project needs. + +#### Scenario: Using default template + +- **WHEN** no custom ADR template is configured +- **THEN** the system SHALL provide a built-in default ADR template +- **AND** the default template SHALL include standard sections (Context, Decision, Options, Consequences) + +#### Scenario: Customizing ADR template + +- **WHEN** a project needs a specific ADR format +- **THEN** create `openspec/templates/adr.md` with the custom template +- **AND** optionally configure the template path in `openspec/config.yaml` +- **AND** the custom template SHALL override the built-in default + +### Requirement: ADR Change Workflow + +ADR changes SHALL follow the same proposal, review, and archive workflow as functional specifications. + +#### Scenario: Creating ADR proposals + +- **WHEN** proposing a new or modified architectural decision +- **THEN** create a change proposal under `openspec/changes/[change-name]/` +- **AND** include ADR deltas in `openspec/changes/[change-name]/adrs/[decision-name]/adr.md` +- **AND** use delta sections: `## ADDED Decisions`, `## MODIFIED Decisions`, `## REMOVED Decisions`, `## RENAMED Decisions` + +#### Scenario: Reviewing ADR changes + +- **WHEN** reviewing an ADR change proposal +- **THEN** validate the ADR format and content +- **AND** ensure the decision is well-justified with context and options +- **AND** verify consequences are clearly documented +- **AND** approve or request changes via normal change review process + +#### Scenario: Archiving ADR changes + +- **WHEN** archiving a completed ADR change +- **THEN** apply delta operations to `openspec/adrs/` directory: + 1. Process RENAMED decisions first + 2. Process REMOVED decisions + 3. Process MODIFIED decisions (update existing ADRs) + 4. Process ADDED decisions (create new ADRs) +- **AND** validate that MODIFIED/REMOVED reference existing ADRs +- **AND** validate that ADDED don't conflict with existing ADRs + +### Requirement: ADR Format Structure + +ADRs SHALL use a two-file structured format optimized for context efficiency and comprehensive documentation. + +#### Scenario: decision.md summary file + +- **WHEN** creating a decision.md file +- **THEN** it SHALL include these fields: + - `# Decision: [Name]` - Title + - `**Status:**` - Accepted | Proposed | Superseded + - `**Scope:**` - Pattern-based description of what this affects + - `**What:**` - One-sentence summary + - `**Key Trade-offs:**` - Major benefits (✓) and drawbacks (✗) + - `**See:**` - Reference to full ADR (./adr.md) +- **AND** keep content concise (~200 tokens) + +#### Scenario: adr.md rationale file + +- **WHEN** creating an adr.md file +- **THEN** it SHALL include these sections: + - `# ADR: [Decision Name]` - Title header + - `## Context` - Detailed background, problem statement, constraints + - `## Options Considered` - Comprehensive alternatives with pros/cons + - `## Decision Rationale` - Detailed explanation of choice + - `## Consequences` - Detailed impacts, migration, trade-offs + - `## References` (optional) - Related specs, ADRs, external resources + +#### Scenario: Pattern-based scope in decision.md + +- **WHEN** writing the Scope field in decision.md +- **THEN** use pattern-based descriptions rather than exhaustive lists: + - Example: "All capabilities requiring non-relational data storage" + - Example: "Authentication and authorization domain" + - Example: "Any spec needing key-value storage or high-throughput writes" +- **AND** MAY include examples: "user-auth (sessions), analytics-events, audit-logs" +- **AND** SHALL NOT require maintaining exhaustive lists + +### Requirement: Cross-Reference Between Specs and ADRs + +Specs and ADRs SHALL support cross-referencing to maintain architectural consistency. + +#### Scenario: Referencing ADRs from spec design docs + +- **WHEN** a spec's implementation depends on architectural decisions +- **THEN** reference the relevant ADR in the spec's `design.md` +- **AND** use format: "See ADR: [decision-name]" or link to the ADR file +- **AND** ensure implementation follows ADR guidance + +#### Scenario: Listing affected specs in ADRs + +- **WHEN** an ADR impacts multiple capabilities +- **THEN** list affected specs in the ADR's References section +- **AND** explain how the decision affects each spec +- **AND** update affected specs to reference the ADR when they're next modified diff --git a/openspec/changes/add-architectural-decision-records/tasks.md b/openspec/changes/add-architectural-decision-records/tasks.md new file mode 100644 index 000000000..97f9c531d --- /dev/null +++ b/openspec/changes/add-architectural-decision-records/tasks.md @@ -0,0 +1,61 @@ +# Implementation Tasks + +## 1. Core Structure and Templates +- [ ] 1.1 Create default decision.md template in `src/core/templates/decision.md` +- [ ] 1.2 Create default adr.md template in `src/core/templates/adr.md` +- [ ] 1.3 Add template management utilities in `src/core/templates/manager.ts` +- [ ] 1.4 Update `openspec init` to create `adrs/` and `templates/` directories +- [ ] 1.5 Add template configuration support to `config.yaml` schema for both decision and adr templates +- [ ] 1.6 Create ADR parser in `src/core/parsers/adr-parser.ts` (handles both files) + +## 2. CLI Command Extensions +- [ ] 2.1 Extend `openspec list` with `--adrs` flag to list ADRs +- [ ] 2.2 Update `openspec show` to display decision.md by default with `--type adr` +- [ ] 2.3 Add `--full` flag to `openspec show` to display adr.md instead +- [ ] 2.4 Extend `openspec validate` to validate ADR deltas in changes (both files) +- [ ] 2.5 Update `openspec archive` to apply ADR deltas to `adrs/` directory (both files) +- [ ] 2.6 Update command help text and examples for ADR support + +## 3. ADR Delta Processing +- [ ] 3.1 Implement ADR delta parser (ADDED/MODIFIED/REMOVED/RENAMED Decisions) +- [ ] 3.2 Add ADR validation rules (decision format, context, options, consequences) +- [ ] 3.3 Implement ADR archiving logic (apply deltas from changes to adrs/) +- [ ] 3.4 Add conflict detection for overlapping ADR changes +- [ ] 3.5 Create ADR diff display utilities for CLI output + +## 4. Documentation Updates +- [ ] 4.1 Update `openspec/AGENTS.md` with ADR workflow instructions +- [ ] 4.2 Add proactive ADR detection guidance to `AGENTS.md` +- [ ] 4.3 Include decision tree/checklist for when to create ADRs in `AGENTS.md` +- [ ] 4.4 Add concrete examples of ADR extraction from user requests to `AGENTS.md` +- [ ] 4.5 Add ADR examples to documentation +- [ ] 4.6 Update `openspec/project.md` to mention ADR structure +- [ ] 4.7 Create migration guide for teams adopting ADRs + +## 5. Specification Deltas +- [ ] 5.1 Create delta for `openspec-conventions` spec (ADR concepts) +- [ ] 5.2 Create delta for `cli-list` spec (ADR listing) +- [ ] 5.3 Create delta for `cli-show` spec (ADR display) +- [ ] 5.4 Create delta for `cli-validate` spec (ADR validation) +- [ ] 5.5 Create delta for `cli-archive` spec (ADR archiving) +- [ ] 5.6 Create delta for `change-creation` spec (ADR changes) +- [ ] 5.7 Create delta for `instruction-loader` spec (ADR context) +- [ ] 5.8 Create delta for `cli-config` spec (template configuration) +- [ ] 5.9 Create new `adr-management` spec + +## 6. Testing +- [ ] 6.1 Add tests for ADR parser +- [ ] 6.2 Add tests for template management +- [ ] 6.3 Add tests for ADR validation +- [ ] 6.4 Add tests for ADR archiving +- [ ] 6.5 Test cross-platform path handling for ADR directories +- [ ] 6.6 Manual testing: Create, validate, and archive an ADR change + +## 7. Integration +- [ ] 7.1 Ensure ADRs appear in `openspec list` output when relevant +- [ ] 7.2 Update instruction loader to load decision.md files for efficient AI context +- [ ] 7.3 Add on-demand loading of adr.md when full rationale needed +- [ ] 7.4 Verify ADR template customization workflow (both files) +- [ ] 7.5 Test complete end-to-end ADR proposal workflow +- [ ] 7.6 Update `openspec update` command to refresh ADR templates if needed +- [ ] 7.7 Verify context efficiency: ~200 tokens per decision.md vs ~1000+ per full ADR