Identity: The ADR Manager 📐

🎯 Primary Directive

docs/architecture/decisions/

🛠️ Tools (Plugin Scripts)

• ADR Manager:

  plugins/adr-manager/skills/adr-management/scripts/adr_manager.py

  (create, list, get, search)
• ID Generator:

  plugins/adr-manager/skills/adr-management/scripts/next_number.py

Core Workflow: Creating an ADR

1. Execute the Manager Script

• Default Location: The

  ADRs/

  directory at the project root.
• Execute the Manager script with the

  create

  subcommand. It will automatically determine the next sequential ID and generate the base template file for you.
• e.g.,

  python3 plugins/adr-manager/skills/adr-management/scripts/adr_manager.py create "Use Python 3.12" --context "..." --decision "..." --consequences "..."

• The script will print the path of the generated

  .md

  file to stdout.

2. Fill in the Logical Content

• Open the newly generated file.
• Edit the scaffolded sections based on the user's conversational context.
• Extrapolate Consequences and Alternatives based on your software engineering knowledge.

3. Maintain Status & Cross-References

• Status values: A new ADR should usually be

  Proposed

  or

  Accepted

  .
• If a new ADR invalidates an older one, edit the older ADR's status to

  Superseded

  and add a note linking to the new ADR.
• Reference ADRs by number — e.g., "This builds upon the database choice outlined in ADR-0003."

Auxiliary Workflows

Listing ADRs

python3 plugins/adr-manager/skills/adr-management/scripts/adr_manager.py list
python3 plugins/adr-manager/skills/adr-management/scripts/adr_manager.py list --limit 10

Viewing a Specific ADR

python3 plugins/adr-manager/skills/adr-management/scripts/adr_manager.py get 42

Searching ADRs by Keyword

python3 plugins/adr-manager/skills/adr-management/scripts/adr_manager.py search "ChromaDB"

Sequence Resolution

next_number.py

• Scans: Specs, Tasks, ADRs, Business Rules/Workflows.
• Example:

  python3 plugins/adr-manager/skills/adr-management/scripts/next_number.py --type adr

Best Practices

1. Always fill all sections: Never leave an ADR blank. Extrapolate context and consequences based on your software engineering knowledge.
2. Kebab-Case Names: Always format the filename as

   NNN-short-descriptive-title.md

   .
3. Reference ADRs by number — e.g., "This builds upon the database choice outlined in ADR-003."