architecture-docs
Use when designing a system or project as a whole - ADRs, component and sequence diagrams, versions, roadmap and change candidates
- License 许可
- MIT
- 最近更新
- 2026-10-30
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- architecture-docs
- description
- Use when designing a system or project as a whole - ADRs, component and sequence diagrams, versions, roadmap and change candidates
02 资源文件 4
- 参考文档templates/adr.md257 B
- 参考文档templates/candidate.md128 B
- 参考文档templates/poc-readme.md219 B
- 参考文档templates/poc-result.md293 B
03 SKILL.md 正文
Architecture documents
System-level work for the architect. Changes to code go through the orchestrator; this skill produces the thinking and the hand-off.
Where
Write only under ~/specs/<project>/architecture: adr/, diagrams/, roadmap.md, backlog/, poc/. If the folder does not exist, create it inside the specs repository (run git init there if the repository is missing). Never write change specs or tasks.
ADRs
- Use templates/adr.md, numbered
adr/NNN-<slug>.md. - Record rejected alternatives in every ADR.
- Link evidence: diagrams, PoC results, measurements.
- Pass ADRs through the humanize skill.
Diagrams
Diagrams are Mermaid: C4 component diagrams and sequence diagrams.
Keep one diagram per file in diagrams/ (<name>.md with a mermaid code block) so diffs stay readable.
Roadmap and versions
roadmap.md lists versions with their goals, the decisions they depend on (ADR links) and open questions.
Hand-off to execution
Hand work to execution only as a candidate card in backlog/ from templates/candidate.md.
The user starts it with /change <slug>; the orchestrator reads the card and its links.
Project docs
Copy diagrams into the work repository docs/ only when the user explicitly asks in this session.
Work style
- Read code through the explorer subagent; do not guess how things are built.
- Discuss one question at a time; propose alternatives with a recommendation.
- After an accepted document, commit the specs repository with
~/.config/opencode/bin/specs-commit <project> '<message>'.
Session log
- Keep the log in
~/specs/<project>/architecture/sessions/<YYYY-MM-DD>-<topic>.md. - During the session, append every user answer and decision as soon as it is given and commit it with
~/.config/opencode/bin/specs-commit <project> 'docs(architecture): record <topic> decisions'. - When a decision reached in the session already sits in an ADR or a map, append
Rederived: <ADR or map path>to the log and commit it.
04 同仓库更多 Skills
verify
Use when a change in __SERVICE__ must be checked before review
work-record
Use when you finished work on a tracker task and it must be recorded in the workspace through a merge request.
task-new
Use to create one story in a stream from the stream profile's story template, link it from its scope screens and open a merge request.
task-decompose
Use to split a stream at the decomposition stage into stories - list scope screens without a story, create the accepted stories and close the stage through a merge request.
task-context
Use to gather the context of a story key or a tracker id - its story, stream stage, scope screens, repositories, decisions, mockups and work records.
repos-sync
Use to update clones of your repositories under repos/ and see their branch, lag and uncommitted changes.