feat(architecture): add architecture.md template and auto-merge on archive #512
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
📝 WalkthroughWalkthroughAdds an architecture documentation template and openspec/architecture.md, implements extraction and merging of architectural decisions from a change's design.md into architecture.md during archival, and integrates template generation and init/update flows to surface and create architecture.md. Changes
Sequence Diagram(s)sequenceDiagram
participant Archive as Archive Workflow
participant Design as design.md
participant Apply as architecture-apply
participant Arch as architecture.md
Archive->>Design: Read design.md
Design-->>Archive: design content
Archive->>Apply: hasArchitecturalImpact(content)?
Apply-->>Archive: yes / no
alt Architectural impact detected
Archive->>Apply: extractArchitecturalDecision(content, changeName, date)
Apply-->>Archive: ArchitecturalDecision
Archive->>Arch: Read architecture.md
Arch-->>Archive: current architecture content
Archive->>Apply: appendArchitecturalDecision(currentContent, decision)
Apply-->>Archive: updated architecture content
Archive->>Arch: Write updated architecture.md
Arch-->>Archive: Write confirmed
Archive->>Archive: Log architecture update
else No architectural impact
Archive->>Archive: Skip architecture update
end
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
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 |
Review CompleteYour review story is ready! Comment !reviewfast on this PR to re-generate the story. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/core/archive.ts (1)
231-262: Avoid updating architecture.md before the archive succeeds.If archiving fails (existing archive or rename error), the decision is still appended, which can record a change that was never archived. Move the merge after a successful rename and read design.md from the archived location.
🛠️ Proposed fix
- // Apply architectural decisions to architecture.md if design.md has architectural impact - const archiveDate = this.getArchiveDate(); - const architectureUpdated = await applyArchitecturalDecisions( - targetPath, - changeName!, - changeDir, - archiveDate - ); - if (architectureUpdated) { - console.log('Updated architecture.md with architectural decisions.'); - } - - // Create archive directory with date prefix - const archiveName = `${archiveDate}-${changeName}`; + // Create archive directory with date prefix + const archiveDate = this.getArchiveDate(); + const archiveName = `${archiveDate}-${changeName}`; const archivePath = path.join(archiveDir, archiveName); @@ - await fs.rename(changeDir, archivePath); + await fs.rename(changeDir, archivePath); + + // Apply architectural decisions after successful archive + const architectureUpdated = await applyArchitecturalDecisions( + targetPath, + changeName!, + archivePath, + archiveDate + ); + if (architectureUpdated) { + console.log('Updated architecture.md with architectural decisions.'); + }
🤖 Fix all issues with AI agents
In `@openspec/architecture.md`:
- Around line 55-57: The table row placeholder is malformed because the header
"| Date | Decision | Rationale | Status |" expects four cells but the row
contains only the comment "<!-- Decisions are appended here during archive -->";
fix by either replacing that single-cell row with an empty four-cell row like "|
| | | |" or moving the comment outside the table (e.g., place "<!-- Decisions
are appended here during archive -->" below the table) so the Markdown table
renders correctly in openspec/architecture.md.
In `@src/core/architecture-apply.ts`:
- Around line 28-45: The pattern checking for "API" in hasArchitecturalImpact is
case-sensitive; update the architecturalPatterns array (in the
hasArchitecturalImpact function) to use a case-insensitive regex for API (e.g.,
change /\bAPI\b/ to /\bAPI\b/i or /\bapi\b/i) so occurrences like "api" or "Api"
are detected; keep the rest of the patterns unchanged.
🧹 Nitpick comments (1)
src/core/templates/architecture-template.ts (1)
62-65: Use a valid placeholder for the decisions table.The single-cell placeholder row can render as a malformed table. Consider removing it (the surrounding comments already explain auto-append behavior).
🛠️ Suggested tweak
| Date | Decision | Rationale | Status | |------|----------|-----------|--------| -| <!-- Decisions are appended here during archive --> |
Resolved conflicts in skill-templates.ts: - Combined indentation changes from both branches - Merged guardrail sections for archive-related skills - Kept upstream's improvement about delta specs sync assessment
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Adds a global
architecture.mddocument to OpenSpec for documenting system architecture, components, data flows, and architectural decisions.Changes
New Files
Modified Files
openspec updateFeatures
Created on init/update:
architecture.mdis generated duringopenspec init(new projects) oropenspec update(existing projects)Auto-merge on archive: Architectural decisions from per-change design.md are automatically extracted and appended to the global
architecture.mddecisions tableLLM guidance: AGENTS.md now includes:
User prompts: Both init and update display helpful prompts for populating architecture.md
Template Structure
Testing
zsh-installer.test.ts(unrelated to this PR)Checklist
pnpm installpnpm run buildpnpm test(pre-existing failures only)Summary by CodeRabbit
New Features
Documentation
Workflow Updates
UX
✏️ Tip: You can customize this high-level summary in your review settings.