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

Aperta
#889 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
55/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
markdown

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.
Lingua principale
TypeScript
Stelle
481
Fork
45
Merge medio
14h 36m
PR unite (30g)
110

Guida per i contributori

Apri la guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di ai-driven-dev/framework

Tutte le issue di ai-driven-dev/framework

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.