feat: add change creation utilities #408
Conversation
📝 WalkthroughWalkthroughIntroduces change management utilities (validateChangeName, createChange) for programmatic OpenSpec change directory creation with kebab-case validation. Updates artifact POC documentation to reflect XDG-based schema/template resolution with explicit multi-slice architecture. Includes comprehensive specifications, implementation, and test coverage. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro 📒 Files selected for processing (8)
✅ Files skipped from review due to trivial changes (1)
🧰 Additional context used📓 Path-based instructions (3)openspec/changes/**/*.md📄 CodeRabbit inference engine (openspec/AGENTS.md)
Files:
openspec/specs/**/spec.md📄 CodeRabbit inference engine (openspec/AGENTS.md)
Files:
openspec/changes/**/specs/**/spec.md📄 CodeRabbit inference engine (openspec/AGENTS.md)
Files:
🧠 Learnings (15)📓 Common learnings📚 Learning: 2025-11-25T01:08:19.004ZApplied to files:
📚 Learning: 2025-11-25T01:08:19.004ZApplied to files:
📚 Learning: 2025-11-25T01:08:19.004ZApplied to files:
📚 Learning: 2025-11-25T01:08:19.004ZApplied to files:
📚 Learning: 2025-11-25T01:08:02.839ZApplied to files:
📚 Learning: 2025-11-25T01:08:19.004ZApplied to files:
📚 Learning: 2025-11-25T01:08:19.004ZApplied to files:
📚 Learning: 2025-11-25T01:08:19.004ZApplied to files:
📚 Learning: 2025-11-25T01:08:19.004ZApplied to files:
📚 Learning: 2025-11-25T01:08:19.004ZApplied to files:
📚 Learning: 2025-11-25T01:08:19.004ZApplied to files:
📚 Learning: 2025-11-25T01:08:19.004ZApplied to files:
📚 Learning: 2025-11-25T01:08:19.004ZApplied to files:
📚 Learning: 2025-11-25T01:08:19.004ZApplied to files:
🧬 Code graph analysis (1)test/utils/change-utils.test.ts (2)
🔇 Additional comments (7)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
docs/artifact_poc.md (3)
70-90: Clarify "2 Levels Max" vs. 3-tier fallback.The section title and rule at line 85 say "Max 2 levels," but lines 74–78 show a 3-tier fallback (schema-specific → shared → built-in). Clarify whether this is "2 user-customizable levels + 1 built-in" or update the phrasing to align with 3 tiers.
🔎 Suggested clarification
Either update the title to reflect the 3-tier structure:
-### Template Inheritance (2 Levels Max) +### Template Inheritance (3-Tier Fallback)Or clarify in the rules section:
-**Rules:** +**Rules:** +- Max 2 user-customizable levels (schema-specific, shared); built-in is non-overridable fallback
119-141: Clarify thetemplatefield semantics in ArtifactSchema.Line 128 shows
template: z.string()with no comment. From the Schema YAML example (lines 526, 532, etc.), it appears this is a template filename or relative path that resolves via Slice 3's 2-level fallback. Adding a brief comment would improve clarity.🔎 Suggested clarification
const ArtifactSchema = z.object({ id: z.string().min(1), generates: z.string().min(1), // e.g., "proposal.md" or "specs/*.md" description: z.string(), - template: z.string(), // path to template file + template: z.string(), // template name; resolves via Slice 3's 2-level fallback requires: z.array(z.string()).default([]), });
513-550: Add Slice 3 note to clarify template resolution behavior.The schema YAML example references template filenames (e.g., "proposal.md", "specs.md") but doesn't note that template resolution is deferred to Slice 3's 2-level fallback. Adding a brief comment would prevent confusion about how these filenames are resolved.
🔎 Suggested clarification
After line 520 (after
description: Specification-driven development), add:description: Specification-driven development + + # Note: Template filenames resolve via Slice 3's 2-level fallback: + # 1. ${XDG_DATA_HOME}/openspec/schemas/<schema>/templates/<artifact>.md + # 2. ${XDG_DATA_HOME}/openspec/templates/<artifact>.md + # 3. <package>/templates/<artifact>.mdOr more concisely, add a note after the artifacts block.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
docs/artifact_poc.mdopenspec/changes/add-change-manager/design.mdopenspec/changes/add-change-manager/proposal.mdopenspec/changes/add-change-manager/specs/change-manager/spec.mdopenspec/changes/add-change-manager/tasks.md
🧰 Additional context used
📓 Path-based instructions (4)
openspec/changes/**/*.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Scaffold proposal using
proposal.md,tasks.md, optionaldesign.md, and delta specs underopenspec/changes/<id>/
Files:
openspec/changes/add-change-manager/tasks.mdopenspec/changes/add-change-manager/specs/change-manager/spec.mdopenspec/changes/add-change-manager/design.mdopenspec/changes/add-change-manager/proposal.md
openspec/changes/*/tasks.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Ensure
tasks.mdcontains implementation checklist with numbered sections and checkbox items
Files:
openspec/changes/add-change-manager/tasks.md
openspec/changes/**/specs/**/spec.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
openspec/changes/**/specs/**/spec.md: Use## ADDED|MODIFIED|REMOVED|RENAMED Requirementsheaders in spec delta files
Include at least one#### Scenario:per requirement in spec delta files
Use#### Scenario: Nameformat (4 hashtags) for scenario headers, not bullets or bold text
Use## ADDED Requirementsfor new orthogonal capabilities that can stand alone; use## MODIFIED Requirementsfor behavior changes of existing requirements
When using MODIFIED Requirements, paste the full requirement block including header and all scenarios
Files:
openspec/changes/add-change-manager/specs/change-manager/spec.md
openspec/changes/*/proposal.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Ensure
proposal.mdincludes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Files:
openspec/changes/add-change-manager/proposal.md
🧠 Learnings (15)
📓 Common learnings
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Create `design.md` only when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/tasks.md : Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items
Applied to files:
openspec/changes/add-change-manager/tasks.mdopenspec/changes/add-change-manager/specs/change-manager/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
openspec/changes/add-change-manager/tasks.mdopenspec/changes/add-change-manager/specs/change-manager/spec.mdopenspec/changes/add-change-manager/design.mdopenspec/changes/add-change-manager/proposal.mddocs/artifact_poc.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Create `design.md` only when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity
Applied to files:
openspec/changes/add-change-manager/tasks.mdopenspec/changes/add-change-manager/design.mddocs/artifact_poc.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Applied to files:
openspec/changes/add-change-manager/tasks.mdopenspec/changes/add-change-manager/specs/change-manager/spec.mdopenspec/changes/add-change-manager/design.mdopenspec/changes/add-change-manager/proposal.mddocs/artifact_poc.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Applied to files:
openspec/changes/add-change-manager/tasks.mdopenspec/changes/add-change-manager/specs/change-manager/spec.mdopenspec/changes/add-change-manager/design.mdopenspec/changes/add-change-manager/proposal.mddocs/artifact_poc.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
Applied to files:
openspec/changes/add-change-manager/specs/change-manager/spec.mddocs/artifact_poc.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED Requirements` for new orthogonal capabilities that can stand alone; use `## MODIFIED Requirements` for behavior changes of existing requirements
Applied to files:
openspec/changes/add-change-manager/specs/change-manager/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Run `openspec validate [change-id] --strict` before requesting approval
Applied to files:
openspec/changes/add-change-manager/specs/change-manager/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Include at least one `#### Scenario:` per requirement in spec delta files
Applied to files:
openspec/changes/add-change-manager/specs/change-manager/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Check `openspec/project.md` for project conventions before creating specs
Applied to files:
openspec/changes/add-change-manager/specs/change-manager/spec.mddocs/artifact_poc.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes
Applied to files:
openspec/changes/add-change-manager/specs/change-manager/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : When using MODIFIED Requirements, paste the full requirement block including header and all scenarios
Applied to files:
openspec/changes/add-change-manager/specs/change-manager/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `#### Scenario: Name` format (4 hashtags) for scenario headers, not bullets or bold text
Applied to files:
openspec/changes/add-change-manager/specs/change-manager/spec.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
Applied to files:
docs/artifact_poc.md
🔇 Additional comments (6)
openspec/changes/add-change-manager/tasks.md (1)
1-49: Well-organized implementation checklist aligning with spec.The task list is comprehensive and properly structured with 7 numbered sections and 30 checkbox items across all implementation layers (types, validation, initialization, path resolution, listing, creation, and export). The granularity and sequencing align well with the spec requirements.
openspec/changes/add-change-manager/specs/change-manager/spec.md (1)
1-106: Spec format fully compliant; comprehensive scenario coverage.The specification correctly uses the
## ADDED Requirementsheader and all five requirements are supported by clear, testable scenarios using the proper#### Scenario: Nameformat. A total of 22 scenarios across initialization, creation, listing, path resolution, and validation requirements provides robust coverage of the ChangeManager API surface. All WHEN-THEN conditions are explicit and measurable.openspec/changes/add-change-manager/design.md (2)
29-156: Design documentation is thorough and well-justified.The six design decisions are clearly articulated with alternatives considered, trade-offs acknowledged, and rationale explained. The scope and non-goals are well-defined (template resolution deferred to Slice 3), and the reuse of
artifact-graph's schema resolution avoids duplication. This design.md is appropriate given the architectural significance of the decisions (filesystem-as-database, class-based API, XDG compliance).
75-98: Verify the artifact-graph import path example (Decision 3).Line 81 shows
import { resolveSchema } from './artifact-graph';as a code example. Please confirm this path is correct relative to the ChangeManager module location. The actual path may differ depending on the final module structure (e.g., could be../core/artifact-graphor similar).openspec/changes/add-change-manager/proposal.md (1)
54-61: Impact section clearly articulates scope.The impact assessment correctly identifies no affected specs (new capability), specifies the new spec and implementation files, and declares the dependency on
artifact-graphfor schema resolution. This is clear and complete for a new module introduction.docs/artifact_poc.md (1)
554-569: Summary table status alignment check.The Summary table shows ArtifactGraph as "✅ Slice 1" (complete) and ChangeManager as "Slice 2" (in progress). Verify this matches the actual PR status—per PR objectives, Slice 1 is marked complete and Slice 2 (ChangeManager) is proposed in this PR. The table appears accurate but confirm final status labeling with the PR branch.
|
|
||
| 2. **Initialization Check** | ||
| - `isInitialized()` - Check if `openspec/` directory exists (project has changes) |
There was a problem hiding this comment.
Correct the isInitialized() description to match design.md.
Line 22 states: "isInitialized() - Check if openspec/ directory exists (project has changes)"
However, design.md Decision 2 (line 61) specifies: "Project initialized? | openspec/changes/ exists"
These should be consistent. Based on the directory structure (lines 40–47) and the context that changes live under openspec/changes/, the check should verify that openspec/changes/ exists, not just openspec/.
🔎 Proposed fix
- - `isInitialized()` - Check if `openspec/` directory exists (project has changes)
+ - `isInitialized()` - Check if `openspec/changes/` directory exists📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 2. **Initialization Check** | |
| - `isInitialized()` - Check if `openspec/` directory exists (project has changes) | |
| 2. **Initialization Check** | |
| - `isInitialized()` - Check if `openspec/changes/` directory exists |
🤖 Prompt for AI Agents
In openspec/changes/add-change-manager/proposal.md around lines 20 to 22, the
description of isInitialized() incorrectly says it checks for openspec/; update
it to state it checks for openspec/changes/ so it matches design.md Decision 2
and the directory structure; change the text to read something like:
"`isInitialized()` - Check if `openspec/changes/` directory exists (project has
changes)" so the documentation is consistent.
Review CompleteYour review story is ready! Comment !reviewfast on this PR to re-generate the story. |
Slice 2 of the artifact tracker POC. Creates ChangeManager module that: **Extracts existing functionality:** - `listChanges()` from ListCommand + ChangeCommand.getActiveChanges() - `changeExists()` from inline fs.access() checks - `getChangePath()` from inline path.join() calls - `isInitialized()` from ListCommand directory check **Adds new functionality:** - `createChange(name, description?)` - create change directory + README - `validateName(name)` - enforce kebab-case naming **Refactors CLI commands to be thin wrappers:** - ListCommand delegates to ChangeManager - ChangeCommand delegates to ChangeManager Also updates docs/artifact_poc.md to reflect XDG decisions from Slice 1.
TabishB
force-pushed
the
add-change-manager
branch
from
835b3ab to
653f2c9
Compare
TabishB
changed the title
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
openspec/changes/add-change-manager/proposal.md (1)
22-22: Fix inconsistentisInitialized()description.Line 22 states that
isInitialized()checks foropenspec/directory, but design.md Decision 2 (line 61) and the directory structure context indicate it should check foropenspec/changes/existence. This matches the behavior described in the spec.md (lines 59–65).🔎 Proposed fix
- - `isInitialized()` - Check if `openspec/` directory exists (project has changes) + - `isInitialized()` - Check if `openspec/changes/` directory existsThis was flagged in a previous review and should be corrected for consistency across proposal, design, and spec documents.
🧹 Nitpick comments (5)
docs/artifact_poc.md (5)
54-57: Add language identifier to schema resolution example.Fenced code blocks should specify a language identifier for proper syntax highlighting. This block (lines 54–57) shows YAML paths and should be marked as YAML or plaintext.
🔎 Proposed fix
-``` +```yaml 1. ${XDG_DATA_HOME}/openspec/schemas/<name>.yaml # Global user override 2. <package>/schemas/<name>.yaml # Built-in defaults -``` +```
74-78: Add language identifier to template resolution example.Fenced code blocks should specify a language identifier. This block (lines 74–78) contains configuration paths and should be marked as a shell or plaintext block.
🔎 Proposed fix
-``` +``` 1. ${XDG_DATA_HOME}/openspec/schemas/<schema>/templates/<artifact>.md # Schema-specific 2. ${XDG_DATA_HOME}/openspec/templates/<artifact>.md # Shared 3. <package>/templates/<artifact>.md # Built-in fallback -``` +```Note: This fallback chain doesn't follow executable syntax, so plaintext (no language specified) is acceptable.
166-168: Add language identifier to change directory paths example.Fenced code blocks should specify a language identifier. This block (lines 166–168) shows file paths and should be marked explicitly.
🔎 Proposed fix
-``` +``` openspec/changes/<name>/ → Change instances with artifacts (project-level) -``` +```
333-339: Add language identifier to XDG schema resolution flow.Fenced code blocks should specify a language identifier. This block (lines 333–339) shows a resolution flow and should be marked appropriately.
🔎 Proposed fix
-``` +``` ${XDG_DATA_HOME}/openspec/schemas/<name>.yaml # User override ↓ (not found) <package>/schemas/<name>.yaml # Built-in ↓ (not found) Error (schema not found) -``` +```
343-351: Add language identifier to template fallback flow.Fenced code blocks should specify a language identifier. This block (lines 343–351) shows a resolution flow and should be marked appropriately.
🔎 Proposed fix
-``` +``` ${XDG_DATA_HOME}/openspec/schemas/<schema>/templates/<artifact>.md # Schema-specific ↓ (not found) ${XDG_DATA_HOME}/openspec/templates/<artifact>.md # Shared ↓ (not found) <package>/templates/<artifact>.md # Built-in ↓ (not found) Error (no silent fallback to avoid confusion) -``` +```
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
docs/artifact_poc.mdopenspec/changes/add-change-manager/design.mdopenspec/changes/add-change-manager/proposal.mdopenspec/changes/add-change-manager/specs/change-manager/spec.mdopenspec/changes/add-change-manager/tasks.md
🚧 Files skipped from review as they are similar to previous changes (1)
- openspec/changes/add-change-manager/tasks.md
🧰 Additional context used
📓 Path-based instructions (3)
openspec/changes/**/*.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Scaffold proposal using
proposal.md,tasks.md, optionaldesign.md, and delta specs underopenspec/changes/<id>/
Files:
openspec/changes/add-change-manager/proposal.mdopenspec/changes/add-change-manager/specs/change-manager/spec.mdopenspec/changes/add-change-manager/design.md
openspec/changes/*/proposal.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Ensure
proposal.mdincludes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Files:
openspec/changes/add-change-manager/proposal.md
openspec/changes/**/specs/**/spec.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
openspec/changes/**/specs/**/spec.md: Use## ADDED|MODIFIED|REMOVED|RENAMED Requirementsheaders in spec delta files
Include at least one#### Scenario:per requirement in spec delta files
Use#### Scenario: Nameformat (4 hashtags) for scenario headers, not bullets or bold text
Use## ADDED Requirementsfor new orthogonal capabilities that can stand alone; use## MODIFIED Requirementsfor behavior changes of existing requirements
When using MODIFIED Requirements, paste the full requirement block including header and all scenarios
Files:
openspec/changes/add-change-manager/specs/change-manager/spec.md
🧠 Learnings (16)
📓 Common learnings
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
openspec/changes/add-change-manager/proposal.mddocs/artifact_poc.mdopenspec/changes/add-change-manager/specs/change-manager/spec.mdopenspec/changes/add-change-manager/design.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Applied to files:
openspec/changes/add-change-manager/proposal.mddocs/artifact_poc.mdopenspec/changes/add-change-manager/specs/change-manager/spec.mdopenspec/changes/add-change-manager/design.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Use kebab-case, verb-led change IDs: `add-`, `update-`, `remove-`, `refactor-`
Applied to files:
openspec/changes/add-change-manager/proposal.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Create `design.md` only when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity
Applied to files:
docs/artifact_poc.mdopenspec/changes/add-change-manager/design.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Applied to files:
docs/artifact_poc.mdopenspec/changes/add-change-manager/specs/change-manager/spec.mdopenspec/changes/add-change-manager/design.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
Applied to files:
docs/artifact_poc.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Check `openspec/project.md` for project conventions before creating specs
Applied to files:
docs/artifact_poc.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
Applied to files:
openspec/changes/add-change-manager/specs/change-manager/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED Requirements` for new orthogonal capabilities that can stand alone; use `## MODIFIED Requirements` for behavior changes of existing requirements
Applied to files:
openspec/changes/add-change-manager/specs/change-manager/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Include at least one `#### Scenario:` per requirement in spec delta files
Applied to files:
openspec/changes/add-change-manager/specs/change-manager/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes
Applied to files:
openspec/changes/add-change-manager/specs/change-manager/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Run `openspec validate [change-id] --strict` before requesting approval
Applied to files:
openspec/changes/add-change-manager/specs/change-manager/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : When using MODIFIED Requirements, paste the full requirement block including header and all scenarios
Applied to files:
openspec/changes/add-change-manager/specs/change-manager/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/tasks.md : Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items
Applied to files:
openspec/changes/add-change-manager/specs/change-manager/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `#### Scenario: Name` format (4 hashtags) for scenario headers, not bullets or bold text
Applied to files:
openspec/changes/add-change-manager/specs/change-manager/spec.md
🪛 LanguageTool
openspec/changes/add-change-manager/proposal.md
[style] ~58-~58: This phrase is redundant (‘I’ stands for ‘interface’). Use simply “CLI”.
Context: ...lices 3/4 - Breaking changes: None (CLI interface unchanged)
(ACRONYM_TAUTOLOGY)
🪛 markdownlint-cli2 (0.18.1)
docs/artifact_poc.md
54-54: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
74-74: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
166-166: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
333-333: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
343-343: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (3)
openspec/changes/add-change-manager/design.md (1)
1-176: Comprehensive design document with clear decision rationale.The design.md provides well-structured architectural guidance with six key decisions, migration phases, and risk mitigation. The decisions appropriately balance extraction of existing logic with new functionality (createChange, validateName). The migration plan (5 phases) is clear and testable.
One clarification: Decision 2 shows the constructor signature as
constructor(options: { projectRoot: string }), but this should be verified against the final implementation to ensure consistency with how ChangeManager will be instantiated in ListCommand and ChangeCommand.Verify that the ChangeManager constructor and method signatures in design.md Decision 2 (lines 56–68) match the final implementation once coding begins, especially the options object shape.
openspec/changes/add-change-manager/specs/change-manager/spec.md (1)
1-137: Properly structured spec with correct requirement headers and scenario format.The spec correctly uses
## ADDED Requirementsand consistently applies the#### Scenario: Nameformat (4 hashtags) for all 17 scenarios across 5 requirements. Each requirement includes at least one scenario as required by guidelines. The spec aligns well with the design.md decisions and proposal.md API surface.The scenarios comprehensively cover both happy paths and error cases (e.g., duplicate change rejection at lines 82–84, invalid name rejection at lines 90–92).
docs/artifact_poc.md (1)
153-178: ChangeManager section aligns well with supporting documents.Lines 153–178 clearly position ChangeManager (Slice 2) as the change CRUD layer with appropriate scope boundaries. The note at line 177 ("Schema resolution is handled by artifact-graph module (Slice 1). Template resolution is handled by InstructionLoader (Slice 3).") correctly delineates responsibilities and prevents duplication.
The list of key methods (lines 171–175) matches the spec.md requirements and design.md API surface.
| - Refactor: `src/core/list.ts` - Use ChangeManager | ||
| - Refactor: `src/commands/change.ts` - Use ChangeManager | ||
| - **Dependencies**: Used by `artifact-graph` for Slices 3/4 | ||
| - **Breaking changes**: None (CLI interface unchanged) |
There was a problem hiding this comment.
Remove redundant acronym expansion.
Line 58 uses the redundant phrase "CLI interface" (the 'I' in CLI already stands for 'interface'). Per static analysis tools, this should be simplified to just "CLI".
🔎 Proposed fix
-- **Breaking changes**: None (CLI interface unchanged)
+- **Breaking changes**: None (no CLI changes)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - **Breaking changes**: None (CLI interface unchanged) | |
| - **Breaking changes**: None (no CLI changes) |
🧰 Tools
🪛 LanguageTool
[style] ~58-~58: This phrase is redundant (‘I’ stands for ‘interface’). Use simply “CLI”.
Context: ...lices 3/4 - Breaking changes: None (CLI interface unchanged)
(ACRONYM_TAUTOLOGY)
🤖 Prompt for AI Agents
In openspec/changes/add-change-manager/proposal.md around line 58, the phrase
"CLI interface" redundantly expands the acronym; update the line to use "CLI"
only (e.g., change "- **Breaking changes**: None (CLI interface unchanged)" to
"- **Breaking changes**: None (CLI unchanged)") so the acronym isn't repeated
and wording remains concise.
Remove extraction/refactor scope. Just add: - createChange(projectRoot, name, description?) - validateChangeName(name) Simple utility functions in src/utils/change-utils.ts. No class, no abstraction layer.
TabishB
changed the title
- Rename ChangeManager to change-utils (simple utility functions) - Remove extracted methods (listChanges, getChangePath, etc.) - Keep only new functionality: createChange(), validateChangeName() - Update component diagram and summary table
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
docs/artifact_poc.md (1)
176-206: ChangeState data model and Slice 3 responsibilities are well-defined.The
ChangeStateclass withcompleted: Set<string>aligns with enriched summary. Key methods (getTemplatePath(),getEnrichedInstructions(),getChangeStatus()) are clearly scoped. The 2-level template fallback explained here is consistent with line 72 claim (though see prior comment on 2-level vs 3-level naming).
🧹 Nitpick comments (1)
docs/artifact_poc.md (1)
50-68: Schema resolution section is clear, but verify XDG platform defaults.The XDG Base Directory Specification paths are well-documented. Platform paths at lines 60-62 look correct for Unix/macOS/Windows. Consider whether these defaults should be verified against current XDG spec or if a link to external documentation would help readers validate.
You may want to add a brief reference or link to the XDG Base Directory Specification for readers unfamiliar with the standard, e.g.: "See XDG Base Directory spec for details."
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/artifact_poc.md
🧰 Additional context used
🧠 Learnings (7)
📓 Common learnings
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Use kebab-case, verb-led change IDs: `add-`, `update-`, `remove-`, `refactor-`
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Applied to files:
docs/artifact_poc.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
docs/artifact_poc.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Create `design.md` only when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity
Applied to files:
docs/artifact_poc.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Applied to files:
docs/artifact_poc.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
Applied to files:
docs/artifact_poc.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Check `openspec/project.md` for project conventions before creating specs
Applied to files:
docs/artifact_poc.md
🪛 markdownlint-cli2 (0.18.1)
docs/artifact_poc.md
54-54: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
74-74: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
164-164: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
329-329: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
339-339: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (3)
docs/artifact_poc.md (3)
119-141: Type definitions in code block are clear and properly scoped.The Zod validation schemas and derived types correctly document the data structures. Artifact schema with
generatesglob support andrequiresarray is well-defined.Set<string>for completion state is a good choice (immutable, functional).
153-172: Change Utilities scope is appropriately minimalist per PR objectives.The decision to keep only
createChange()andvalidateChangeName()rather than extracting broader ChangeManager is well-justified (line 439 rationale is sound). Existing CLI commands already handle listing and path checks—no need to duplicate. Slice 2 scope is crisp and defensible.
405-440: Slice 1 marked COMPLETE; Slice 2 scope clearly justified.The detailed breakdown of Slice 1 implementation (types, schema parsing, graph, state detection, resolver, built-in schemas) is thorough. Slice 2 explanation (lines 425–440) explicitly addresses why no broader extraction—the existing CLI logic is small and already works. This aligns well with PR objectives and shows intentional scope minimization rather than oversight.
Note: Ensure
src/utils/change-utils.tsand its tests are provided in the PR. From the provided context, only documentation is shown.Please confirm that:
src/utils/change-utils.ts(withcreateChange()andvalidateChangeName()) is implemented.- Unit tests for these utilities are included.
- No refactoring of
ListCommandorChangeCommandwas done (per scope).If these files are in the PR, can you share them for validation of the implementation against this spec?
|
|
||
| Schemas follow the XDG Base Directory Specification with a 2-level resolution: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat -n docs/artifact_poc.md | head -100Repository: Fission-AI/OpenSpec
Length of output: 4451
🏁 Script executed:
cat -n docs/artifact_poc.md | sed -n '54p;74p;164p;329p;339p'Repository: Fission-AI/OpenSpec
Length of output: 119
🏁 Script executed:
# Check context around line 54
sed -n '50,65p' docs/artifact_poc.md
# Check context around line 74
sed -n '70,85p' docs/artifact_poc.md
# Check context around line 164
sed -n '160,175p' docs/artifact_poc.md
# Check context around line 329
sed -n '325,340p' docs/artifact_poc.md
# Check context around line 339
sed -n '335,350p' docs/artifact_poc.mdRepository: Fission-AI/OpenSpec
Length of output: 2676
Add language identifiers to fenced code blocks.
Five code blocks lack language specifiers:
- Line 54: Schema resolution example (add
```yamlor```text) - Line 74: Template inheritance resolution (add
```text) - Line 164: Change paths structure (add
```text) - Line 329: XDG resolution flow diagram (add
```text) - Line 339: Template fallback flow diagram (add
```text)
This ensures markdownlint compliance and enables syntax highlighting in rendered markdown.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
54-54: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In docs/artifact_poc.md around line 54 (and also at lines 74, 164, 329, 339),
several fenced code blocks are missing language identifiers; add appropriate
language tags to each opening fence (e.g., ```yaml or ```text as noted) so
markdownlint passes and syntax highlighting is enabled, making sure each code
block's opening fence is updated with the correct language specifier consistent
with the block content.
| Templates also use 2-level resolution (to be implemented in Slice 3): | ||
|
|
||
| ``` | ||
| .openspec/ | ||
| ├── templates/ # Shared (Level 1) | ||
| │ ├── proposal.md | ||
| │ ├── design.md | ||
| │ └── specs.md | ||
| │ | ||
| └── schemas/ | ||
| └── tdd/ | ||
| ├── schema.yaml | ||
| └── templates/ # Overrides (Level 2) | ||
| └── tests.md # TDD-specific | ||
| 1. ${XDG_DATA_HOME}/openspec/schemas/<schema>/templates/<artifact>.md # Schema-specific | ||
| 2. ${XDG_DATA_HOME}/openspec/templates/<artifact>.md # Shared | ||
| 3. <package>/templates/<artifact>.md # Built-in fallback | ||
| ``` | ||
|
|
||
| **Rules:** | ||
| - Shared templates are the default | ||
| - Schema-specific templates override OR add new | ||
| - Schema-specific templates override shared templates | ||
| - Shared templates override package built-ins | ||
| - A CLI command shows resolved paths (no guessing) | ||
| - No inheritance between schemas (copy if you need to diverge) | ||
| - Max 2 levels - no deeper inheritance chains |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cd /tmp && find . -name "artifact_poc.md" -o -name "*.md" | grep artifact | head -20Repository: Fission-AI/OpenSpec
Length of output: 45
🏁 Script executed:
fd artifact_poc.mdRepository: Fission-AI/OpenSpec
Length of output: 83
🏁 Script executed:
cat -n docs/artifact_poc.md | sed -n '70,90p'Repository: Fission-AI/OpenSpec
Length of output: 1030
🏁 Script executed:
rg -i "2-level|three.tier|schema.*shared.*built" docs/Repository: Fission-AI/OpenSpec
Length of output: 735
🏁 Script executed:
rg -i "template.*resolution|template.*inheritance" docs/ -A 3 -B 3Repository: Fission-AI/OpenSpec
Length of output: 1747
🏁 Script executed:
cat -n docs/artifact_poc.md | sed -n '60,95p'Repository: Fission-AI/OpenSpec
Length of output: 1561
🏁 Script executed:
cat -n docs/artifact_poc.md | sed -n '45,70p'Repository: Fission-AI/OpenSpec
Length of output: 1149
🏁 Script executed:
rg -i "user.override|customizable|two.*level|package.*built" docs/ -B 2 -A 2Repository: Fission-AI/OpenSpec
Length of output: 3479
Update "2-level resolution" terminology to "3-level resolution" for templates.
The template fallback section correctly lists 3 tiers (schema-specific, shared, built-in) but incorrectly labels it as "2-level resolution" in line 72 and "Max 2 levels" in line 85. This conflicts with the schema resolution section, which accurately uses "2-level resolution" for its 2-tier system (user override + built-in). The template rules explicitly describe all 3 tiers overriding each other.
Update:
- Line 72: Change "Templates also use 2-level resolution" to "Templates also use 3-level resolution"
- Line 85: Change "Max 2 levels" to "Max 3 levels"
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
74-74: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In docs/artifact_poc.md around lines 72 to 85, the phrase "2-level resolution"
and "Max 2 levels" incorrectly describe the template fallback mechanism which
actually has three tiers; change the wording to "3-level resolution" at line 72
and "Max 3 levels" at line 85 so the text matches the three listed template
tiers (schema-specific, shared, built-in) and the rules that follow.
Audit artifact_poc.md against existing codebase to mark what already exists vs what's genuinely new: - Slice 4 CLI table: Added Status column (NEW/EXISTS) - Added "Existing CLI commands" section listing what's not in scope - Updated Implementation Order Slice 4 with explicit new vs existing - Summary table: Updated status + added "What already exists" section Key finding: The document was already well-simplified. Only truly new functionality (createChange, validateChangeName, InstructionLoader, artifact graph CLI commands) is proposed.
The capability name "change-manager" implied a manager class abstraction, but the simplified proposal uses only utility functions. Renamed to "change-creation" to accurately reflect what the capability provides.
Add createChange() and validateChangeName() functions for programmatic change directory creation with kebab-case validation. - createChange(projectRoot, name) creates openspec/changes/<name>/ - validateChangeName() enforces kebab-case naming conventions - Comprehensive test coverage (21 tests)
Move change to archive and create change-creation spec with requirements for createChange() and validateChangeName().
TabishB
changed the title
Summary
Add utility functions for programmatic change creation (Slice 2 of artifact tracker POC).
New utilities:
createChange(projectRoot, name, description?)- Creates change directory + README.mdvalidateChangeName(name)- Kebab-case validationLocation:
src/utils/change-utils.tsScope: New functionality only. No refactoring of existing CLI commands.
Why simplified?
Originally proposed extracting existing logic into a ChangeManager class. After analysis:
ListCommandandChangeCommandworks fine (~15 lines each)SpecCommandfor consistencyThe only truly new functionality needed is
createChange()+ name validation. Simple utility functions are sufficient.🤖 Generated with Claude Code
Summary by CodeRabbit
Release Notes
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.