feat(aidd-dev): make architecture impact explicit during planning

Đang mở
#889 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
55/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
markdown

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.
Ngôn ngữ chính
TypeScript
Star
481
Fork
45
Merge trung bình
14 giờ 36 phút
Pull request đã merge (30 ngày)
110

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của ai-driven-dev/framework

Tất cả issue của ai-driven-dev/framework

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.