Project Docs in the Repository

Core principle

The AIDD-17 project definition should be versioned with the code it governs.

Why docs should live with the project

AIDD-17 works best when project documentation and implementation move together.

Keeping the docs in the project repository makes it easier to:

• review code and definition changes together
• trace implementation slices to project intent
• keep architecture and interfaces current
• detect feature drift during pull request review
• understand why changes were made
• onboard humans and AI agents with the same context

If the docs are separate from the code, they are more likely to become stale.

Recommended structure

For a simple project, keep the AIDD-17 definition inside the main repository.

project-root

project-root/
  src/
  tests/
  docs/
    aidd-17/
      project-definition.mdx
      implementation-plan.mdx
      decisions/
      slices/
      verification/

For a project using an Astro Starlight documentation site, keep content inside the docs site but version it with the project.

project-root

project-root/
  src/
  tests/
  docs-site/
    src/content/docs/
      aidd-17/
        index.mdx
        guides/
        templates/
        decisions/
        slices/

Shared framework vs project-specific docs

AIDD-17 has two different kinds of documentation:

Shared framework

Reusable material that can be shared across projects:

• templates
• guidance
• examples
• process pages
• standard review checklists

Project-specific docs

Live project material that belongs with the code:

• actual project definition
• actual implementation plan
• actual decision records
• actual slices
• actual verification records
• project-specific rules

Submodule option

A Git submodule can work for the shared AIDD-17 framework, especially when multiple projects should use the same templates and guidance.

Example:

project-root

project-root/
  aidd-17-framework/        # shared submodule
  docs/aidd-17/             # project-specific docs
  src/
  tests/

Use the submodule for reusable guidance. Keep the live project definition in the project repository.

Avoid separating live intent

Do not place the only copy of the live project definition in a separate repository unless the implementation review process also requires that repository to be updated. Otherwise the definition can drift away from the code.

Pull request rule

When implementation changes affect behaviour, architecture, interfaces, data, or verification, the pull request should include the relevant documentation update.

A pull request should answer:

• Which AIDD-17 slice does this implement?
• Which behaviours or features does this satisfy?
• Which decisions does this rely on?
• Did any project definition change?
• Did any follow-up slice get created?
• Was feature drift checked?

Suggested pull request checklist

pull-request-checklist.txt

AIDD-17 review:

- [ ] Linked implementation slice
- [ ] Linked behaviours or features
- [ ] Scope stayed inside the slice
- [ ] No unapproved feature drift
- [ ] Tests added or updated
- [ ] Verification criteria met
- [ ] Documentation updated where needed
- [ ] Follow-up slices recorded where needed

Recommendation

Use this split:

Shared AIDD-17 framework: templates, guides, examples, standard process
Project repository: live project definition, slices, decisions, verification records

This gives teams a reusable framework without separating the project intent from the code it controls.