feat(aidd-dev): make architecture impact explicit during planning
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 55/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Active
- Tech stack
- markdown
- Domain
- developer-experience, tooling
Research direction
Start with plugins/aidd-dev/skills/01-plan/actions/02-explore.md, phase-template.md, and plan-template.md to understand the existing projection and Decisions contracts. Review #275, #292, and the architecture assertion files for workflow context. Done means the planning flow records current architecture, intentional delta, and rationale only when needed, without rewriting architecture documentation or changing no-impact features.
Written by the indexing model from the issue text.
Description
Problem
"aidd-dev:01-plan" already records implementation projection, risks, feasibility checks, and architecture-magnitude decisions.
However, a feature can intentionally change the architecture that subsequent work is expected to implement.
For example, the documented architecture may currently be:
Checkout API -> Payment Service
while a feature intentionally proposes:
Checkout API -> Payment Service
|
v
Payment Events
|
v
Fraud Service
The current plan artifacts can record this as a textual "Decision", but they do not explicitly distinguish:
- the architecture the feature starts from;
- the intentional architecture change introduced by the feature;
- an architectural deviation introduced later by implementation.
This distinction matters because architecture conformance currently checks code against documented architecture (architecture memory, C4 diagrams, ADRs, project tree). Until the project's architecture documentation is updated, an intentional feature-level change and accidental architectural drift can therefore look equivalent from a conformance perspective.
Conversely, updating architecture documentation from the resulting code would risk turning an unintended implementation decision into intended architecture.
The missing information is not another architecture format, but an explicit statement of architectural intent at planning time.
Scope
- During "01-plan" exploration, identify whether the feature has an architectural impact beyond its existing file-level architecture projection.
- Distinguish explicitly between:
- no architecture change;
- an intentional architecture change.
- For an intentional change, carry enough information into the plan artifacts to describe:
- the relevant current architecture;
- the proposed architecture delta;
- the rationale.
- Keep this information feature-scoped: it describes what the implementation is intended to change, not a silent rewrite of project architecture documentation.
- Preserve the existing flow unchanged when no architecture change is identified.
Acceptance criteria
- "01-plan" can explicitly distinguish a feature with no architecture change from one that intentionally changes architecture.
- An intentional architecture change records the relevant current state, proposed delta, and rationale in the feature planning artifacts.
- The architecture delta describes architectural boundaries, components, dependencies, or relationships rather than duplicating the existing file-level "Architecture projection".
- Existing architecture-magnitude entries in "plan.md > Decisions" remain usable and are not duplicated without purpose.
- The architecture intent is persisted before implementation rather than inferred from the resulting code.
- No architecture documentation is automatically rewritten from implementation code.
- Features without architecture impact require no additional architecture artifact or interaction.
Prior art in this repo
- "plugins/aidd-dev/skills/01-plan/actions/02-explore.md" already produces an architecture projection, but this is currently defined as files to modify, create, or delete with a reason. It does not describe a before/after architecture delta.
- "plugins/aidd-dev/skills/01-plan/assets/phase-template.md" persists that projection as a tree of final files.
- "plugins/aidd-dev/skills/01-plan/assets/plan-template.md" already contains "Decisions" for decisions of "architecture-magnitude", but records only "Decision" and "Why"; it does not capture the architecture state being changed or its intended delta.
- "plugins/aidd-dev/skills/03-assert/actions/02-assert-architecture.md" already checks code against documented architecture sources (architecture memory, diagrams, ADRs, and project tree), which makes explicit feature-level architectural intent potentially useful to later conformance work.
- "plugins/aidd-dev/skills/04-audit/actions/02-architecture.md" similarly checks actual structure against documented modules, layers, and C4 boundaries.
- #275 established the need to persist settled intent across workflow stages rather than let a later agent silently reinterpret it.
- #292 carried that principle into planning by treating settled brainstorm decisions as constraints and surfacing conflicts before plan generation.
- #271 implemented the current "gather -> explore -> wireframe -> plan" flow.
Out of scope
- Adding LikeC4, Structurizr, or another Architecture-as-Code provider.
- Adding a new architecture diagram format.
- Replacing architecture memory, ADRs, C4 diagrams, Mermaid, or the project tree.
- Automatically deriving intended architecture from implementation code.
- Automatically updating project architecture documentation after implementation.
- Defining in this issue how "03-assert" should consume a feature-level architecture delta. That can be considered separately once the planning contract exists.
- Requiring architecture work for features that do not change architecture.
- Dominant language
- TypeScript
- Stars
- 481
- Forks
- 45
- Avg merge
- 17h 40m
- Merged PRs (30d)
- 106
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from ai-driven-dev/framework
-
refactor(aidd-orchestrator): the check zone says when to stop, and reviews its axes in one round Open
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
ai-driven-dev/framework#887 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
ai-driven-dev/framework#873 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
ai-driven-dev/framework#872 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
ai-driven-dev/framework#625 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
ai-driven-dev/framework#467 · 1 comment ·
All issues in ai-driven-dev/framework
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
copse-dev/agent-pane#2953 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
Eynzof/Hermes-CN-Desktop#610 ·
-
bug clawsweeper:linked-pr-open clawsweeper:needs-live-repro clawsweeper:no-new-fix-pr impact:message-loss issue-rating: 🐚 platinum hermit P2 regression
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
calcite-components needs triage refactor
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Esri/calcite-design-system#15203 ·