[Feature]: Provide namespaced organization for aidlc-docs to support multiple intent executions

[doddstr13]

Description

As a team following AIDLC with the aidlc-workflows, we want to be able to

1/ run the workflow 2 or more times for different intents on the project. Meaning after we complete a full workflow execution and deliver results, we want to do it again for a new intent.

2/ run the workflow in parallel for 2 or more different independent components in a mono repo.

Use Case

Customers may have larger brown-field app in a mono repo where they went through a bolt to address a feature which resulted in code being updated in the a component for the mono repo.  Now another component team is looking to use AI-DLC workflow to update that component in a separate intent. 

Need a good way to manage several AI-DLC executions over time in different areas of the mono repo. 

Should the workflow executions be name-spaced in some way?

Could workflow be updated to handle this or at least prescriptive guidance provided?

Area

Inception phase rules

Additional Context

No response

[harmjeff]

AIDLC Folder Structure: Current vs. v2 vs. Alternative — Please Weigh In

We have two proposals to replace the current folder structure. Please read the summaries below and share your preference in the comments. The goal is to agree on a direction before we update the rules.

---

Current Structure (v1 — what the rules specify today)

All AI-DLC documents live inside each code repository, co-located with the code.

<code-repo>/
└── aidlc-docs/
    ├── inception/
    │   ├── plans/
    │   ├── reverse-engineering/      ← brownfield only
    │   ├── requirements/
    │   ├── user-stories/
    │   └── application-design/
    ├── construction/
    │   ├── plans/
    │   ├── <unit-name>/
    │   │   ├── functional-design/
    │   │   ├── nfr-requirements/
    │   │   ├── nfr-design/
    │   │   ├── infrastructure-design/
    │   │   └── code/
    │   └── build-and-test/
    ├── operations/
    ├── aidlc-state.md                ← single shared state file
    └── audit.md                      ← single shared audit trail

Problems this creates (identified in the v2 proposal):

• No Day 2 support. The structure has no provision for a second intent on the same repo.
  Running AIDLC again produces a confusing pile of documents from different points in time.
• Repo bloat. AI-DLC docs are mixed with code. As intents accumulate, the repo fills with
  outdated planning artifacts.
• No cross-repo visibility. Documents are locked inside individual repos. The AI has no
  birds-eye view when an intent spans multiple repositories — the common case in brownfield
  multi-repo engagements.
• DRY violations. Brownfield teams copy aidlc-docs/ across workspaces and duplicate the
  inception phase with no single source of truth.
• Flat state and audit files. Multiple teams writing to aidlc-state.md and audit.md
  during parallel construction causes merge conflicts.
• No intent lifecycle. Ideas have nowhere to live before becoming intents. No staging area,
  no numbering, no review gate.

---

What Both New Proposals Agree On

Both proposals solve the v1 problems with the same foundational move:

• All AI-DLC documents move out of code repos into a central org-ai-kb repository
• codekb/<repo>/ holds reverse-engineered knowledge (summary, architecture, integration
  maps) providing a cross-repo birds-eye view during inception
• aidlc-docs/intent-<nnn>-<name>/ holds per-intent inception and construction artifacts
• Per-unit state/ and audit/ files (no more shared single files — no merge conflicts
  within a single intent)
• Multi-root workspace during construction: teams open org-ai-kb + their target repo
• operations/ and build-and-test/ internal layouts are unspecified in both — placeholders
  only

The difference is in how concurrent intents are isolated and how codekb stays current.

---

Proposal A: v2 (Folder-Based Isolation, Manual codekb Sync)

Core idea: Intent isolation is achieved by folder naming on main. Each intent gets its
own aidlc-docs/intent-<nnn>-<name>/ folder. codekb engineering docs are populated
manually after deployment.

org-ai-kb/
├── codekb/
│   └── <repo>/
│       ├── summary.md              ← RE-generated at onboarding
│       ├── architecture.md
│       ├── integration-map.md
│       ├── intent-history.md
│       └── engineering/
│           └── intent-<nnn>/       ← moved here manually after deployment
│               ├── domain-entities.md
│               ├── business-rules.md
│               ├── nfr-design.md
│               └── infrastructure-design.md
└── aidlc-docs/
    └── intent-<nnn>-<name>/
        ├── state/
        │   ├── intent-state.md
        │   └── <unit-name>-state.md
        ├── audit/
        │   ├── intent-audit.md
        │   └── <unit-name>-audit.md
        ├── inception/
        │   ├── reverse-engineering/
        │   ├── requirements-analysis/
        │   ├── user-stories/
        │   ├── application-design/
        │   └── units-generation/
        └── construction/
            ├── <unit-name>/
            │   ├── functional-design/
            │   ├── nfr-assessment/
            │   ├── nfr-design/
            │   ├── infrastructure-design/
            │   └── code/
            └── build-and-test/

Intent lifecycle: All work happens on main. Two intents running in parallel write to
different intent folders; conflicts are unlikely but not structurally prevented. There is no
formal review gate — artifacts land on main as they are created.

Strengths:

• No CI setup required — works with standard git, no pipeline configuration
• Familiar single-branch workflow, low onboarding friction
• Per-intent engineering docs preserved under codekb give full historical traceability

Weaknesses:

• Parallel intent conflicts not fully solved. Two teams starting different intents
  simultaneously both commit to main. The shared mutable store problem from v1 is shifted up
  one level (from per-unit to per-intent).
• Fragile manual codekb move. Engineering docs must be manually moved to
  codekb/<repo>/engineering/intent-<nnn>/ post-deployment. No tooling enforces it. Under
  delivery pressure this step will be skipped, causing codekb to drift.
• No intent numbering authority. intent-<nnn> folders have no defined owner for the
  counter. Parallel intent creation will collide.
• No formal review gate. No approval step before an intent is considered complete.
• codekb staleness. RE documents are only refreshed when an intent explicitly touches a
  repo. Development outside AIDLC leaves codekb describing a repo as it was, not as it is.

---

Proposal B: Alternative (Branch-Based Isolation, CI-Derived codekb)

Core idea: The git branch is the unit of intent isolation. Active intent work happens
on intent/<nnn>-<name> branches. codekb is CI-derived — after each target repo merges
to its main, a CI job re-runs reverse engineering and overwrites the flat files in
codekb/<repo>/. No manual document move ever occurs. Merging the intent PR to main is the
deployment gate.

Branch model:

Branch	Contents	Who writes
main	Completed intents only; codekb reflects deployed state	CI (for codekb); PR merge (for aidlc-docs)
intent/<nnn>-<name>	Active work — inception + construction artifacts	Teams; deleted after merge

main layout:

org-ai-kb/
├── intent-registry.md              ← authoritative intent list + status + PR numbers
├── codekb/
│   └── <repo>/
│       ├── summary.md              ← CI-generated on every repo merge to main
│       ├── architecture.md
│       ├── integration-map.md
│       ├── domain-entities.md
│       ├── business-rules.md
│       ├── nfr-design.md
│       ├── infrastructure-design.md
│       └── intent-history.md       ← append-only, written by CI
└── aidlc-docs/
    └── intent-<nnn>-<name>/        ← one folder per completed intent; immutable after merge
        ├── state/, audit/
        ├── inception/
        └── construction/<unit-name>/

Intent lifecycle:

1. Create — orchestrator reads intent-registry.md, claims next ID, commits entry to
   main, branches: git checkout -b intent/003-reporting-dashboard
2. Build — all inception and construction artifacts committed to the intent branch
3. Review — orchestrator opens a PR from intent branch → main; reviewers approve all
   artifacts; this is the governance gate
4. Merge — PR merge lands everything on main atomically; CI fires, updates codekb

Strengths:

• True intent isolation. Parallel intents are separate branches — zero file conflicts at
  the git level regardless of how many intents are in flight simultaneously.
• codekb is always current. CI maintains it after every deployment; no drift, no manual
  step.
• Formal review gate. The PR is the governance checkpoint. Reviewers see every artifact
  and every decision. No intent is complete until approved and merged.
• Historical reconstructibility. git log on the commit where an intent branch was
  created shows the exact state of codekb at that moment — no extra tooling needed.
• In-flight change management. A cross-unit change request can be committed to the shared
  intent branch and surfaced via PR review comment or a change-request.md file in the
  affected unit's folder.
• Intent numbering authority. intent-registry.md on main is the sole owner of the
  counter; no collisions.

Weaknesses / Additional requirements:

• CI setup required at onboarding. A CI job must be configured for each target repo to
  write back to org-ai-kb (scoped to codekb/ paths only). Standard practice, but adds
  an onboarding step and requires CI bot write access.
• Intent branch divergence. Long-running intents may diverge from main as other intents
  merge and CI updates codekb. Teams should rebase against main periodically during long
  construction phases.
• RE cost at scale. CI triggers RE on every merge to a target repo's main. Path filters
  (skip re-run if only tests/, docs/, or migrations/ changed) can reduce cost but need
  per-repo configuration at onboarding.
• aidlc-docs growth on main. Historical intent folders accumulate over time. An
  archival strategy (cold-storage branch or separate repo) may be needed for high-volume orgs.
  Not a day 1 problem.

---

Side-by-Side Summary

	Current (v1)	Proposal A (v2)	Proposal B (Alternative)
Docs location	Inside each code repo	Central org-ai-kb	Central org-ai-kb
Cross-repo visibility	None	codekb/ on main	codekb/ on main (CI-maintained)
Intent isolation unit	None	Folder on main	Git branch
Parallel intent conflicts	High	Possible	Impossible (git-level)
codekb freshness	N/A	Manual post-deploy move	CI-derived on every deploy
Intent numbering	None	Ad hoc	intent-registry.md authority
Review gate	None	None	PR required before merge
Historical traceability	None	Per-intent subfolder in codekb	aidlc-docs/intent-<nnn>/ on main + git history
CI requirement	None	None	Yes — one job per target repo
Onboarding complexity	Low	Low	Medium (CI setup)
Day 2 ready	No	Yes	Yes

---

Decision Points — Questions for the Team

1. How often will you run parallel intents? Branch isolation (Proposal B) is the only
   option that makes parallel intents conflict-free at the infrastructure level, not just by
   convention.

2. Can you commit to CI setup at onboarding? Proposal B's codekb guarantee only holds if
   CI is wired up. If customer environments make CI configuration slow or difficult, Proposal A
   is more predictable in the short term.

3. How important is a formal review gate? Proposal B makes the intent PR the governance
   checkpoint. If intent sign-off and artifact review matter to your teams or customers, this
   is a meaningful structural advantage.

4. How much do you trust the manual codekb move in Proposal A? If experience suggests
   post-deployment steps get skipped under delivery pressure, Proposal B removes that risk
   entirely.

5. Does the current rules version (v0.1.7) have engagements already using the v1 structure
   that need migration guidance? Both proposals require teams to move off the existing
   in-repo aidlc-docs/ layout.

---

Please Comment With

• Which proposal you prefer: keep Current (v1), adopt Proposal A (v2), or adopt
  Proposal B (Alternative)
• The one or two factors that most influenced your choice
• Any concerns or questions not covered above

[scottschreckengaust]

Ordered preference:

1. adopt Proposal B (Alternative)
2. adopt Proposal A (v2)
3. keep Current (v1)

Factors that most influenced my choice:

• The ability to have parallel intent without conflicts
• Review gates and scale
• Ability for brownfield customers to be given a mechanism

Concerns

• A CI/CD example (GitHub workflows) should be part of the onboarding
• Although the codekb is by repository, would there be a way to have a "space" that describes how multiple repositories are related to each other or would that be within a section of the intent-registry.md file?

[leandrodamascena]

Hey folks, great discussion here. I like where Proposal B is going, the branch isolation and CI-derived codekb make a lot of sense.

Reading through the proposals and comments, I think there's one thing we haven't explored yet: what the experience actually looks like from the rules perspective once someone is set up and running.

Today every path in the rules is relative to ./aidlc-docs/. With org-ai-kb that changes completely. I think the most natural way to handle this is during workspace detection. If the AI can detect an org-ai-kb in the workspace, it switches to the new path model automatically. That way we keep one set of rules and the developer doesn't need to think about it. But we need to design how that detection works.

The other thing that I think is tricky: session continuity with multiple intents. Today the AI sees aidlc-state.md, knows there's work in progress, and resumes. With multiple intents, there could be two or three in progress at the same time. How does the AI know which one to pick up? Does it ask? Does it look at which intent branch is checked out? I think this needs to feel natural, not like a manual selection step every time you start a session.

Again, I think the direction is right. I just want to make sure we think about how the rules adapt alongside the structure. My suggestion would be to keep v1 working as is and introduce the org-ai-kb model as an alternative that we validate with real engagements before making it the default in v2.

What do you think?

[doddstr13]

Great analysis and suggestions. I prefer Proposal B due to formal review gate, intent isolation, and the CI automation management of the codekb. No additional concerns not covered.

[ayushtr-aws]

I prefer Proposal B due to the following reasons:

• CI/CD pipeline integration. While this will be a big onboarding step for customers, once they have the proper setup, the automation will help them in the long term.
• Introducing manual steps to keep codekb fresh will hinder the user experience; AI-DLC is supposed to increase velocity without introducing new bottlenecks.