@dilankam/architecture-knowledge

Install the Architecture Knowledge @architecture-agent bridge and full local knowledge snapshot into any repository.

Use it when you want ChatGPT, Codex, Claude, Cursor, or GitHub Copilot to help draft architecture decisions, ADRs, solution designs, review reports, risks, and follow-up actions without inventing missing evidence.

🚀 Install

From a consumer repository:

npx @dilankam/architecture-knowledge install

Install into a specific target:

npx @dilankam/architecture-knowledge install --target /path/to/repo

Refresh managed bridge files:

npx @dilankam/architecture-knowledge install --force

Refresh an existing repository with the latest package knowledge:

npx @dilankam/architecture-knowledge@latest update

Create a deterministic enterprise-grade scenario output package:

npx @dilankam/architecture-knowledge scaffold scenario payment-async-retries

The canonical npm package is @dilankam/architecture-knowledge. The executable remains architecture-knowledge, but npx architecture-knowledge install only works if a separate unscoped wrapper package is published later.

Local development from the source repository:

node packages/architecture-knowledge/bin/architecture-knowledge.js install --target /tmp/test-repo

📦 What It Creates

| File | Purpose | | --- | --- | | AGENTS.md | Tells AI clients that @architecture-agent is available | | .github/copilot-instructions.md | Makes the bridge discoverable by GitHub Copilot | | .architecture-knowledge/README.md | Explains the local bridge | | .architecture-knowledge/AGENT.md | Defines local agent behavior and guardrails | | .architecture-knowledge/knowledge/ | Local skills, playbooks, references, runtime, schemas, templates, and indexes | | docs/architecture/scenarios/README.md | Creates a workspace for architecture scenarios and outputs |

Existing files are preserved unless --force is passed.

The knowledge snapshot is refreshed on every install/update unless --skip-knowledge is used.

🧭 Use With Any AI Client

ChatGPT:

@architecture-agent
Intent: solution-design
Input:
Design an order processing modernization and compare synchronous REST with event-driven messaging.
Create a solution design, ADR candidates, risks, and review checklist.

Codex:

@architecture-agent assess this change:
We are moving payment retries from in-request retries to queued asynchronous retries.
Generate ADR candidates, trade-offs, risks, and TODOs for missing evidence.

Claude:

/agent architecture-agent
Intent: architecture-review
Input:
Review this proposed service architecture for reliability, security, integration, and governance concerns.

GitHub Copilot:

@architecture-agent
Intent: adr-generation
Input:
Create ADR candidates for replacing direct database sharing with API-based integration.

Cursor:

@architecture-agent design a solution for this repository change.
Include options, quality attributes, risks, ADR candidates, and pending human review checkpoints.

👥 Common Scenarios

| Role | Ask For | | --- | --- | | Developer or engineer | ADR candidates for a proposed code or platform change | | Software architect | Solution design, trade-offs, quality attributes, and review checklist | | Enterprise architect | Business capability impact, enterprise alignment, risks, governance checkpoints, and ADR candidates |

🗂️ Scenario Folders

Use this convention inside the consumer repository:

docs/architecture/scenarios/<scenario-id>/
  README.md
  input-context.md
  expected-workflow.md
  outputs/

Write generated drafts into the scenario outputs/ directory.

For reliable file generation, scaffold the package first:

npx @dilankam/architecture-knowledge scaffold scenario payment-async-retries

Then ask your AI client:

@architecture-agent assess this change in repository write mode.
Use existing scaffold:
docs/architecture/scenarios/payment-async-retries/
Fill every file under outputs/.
Do not combine files.

The scaffold creates 00-readme.md through 12-evidence-gaps.md with enterprise-grade headings for business, enterprise, solution, technology, security, operational readiness, governance, ADRs, risks, and evidence gaps.

✅ Guardrails

• Do not invent evidence.
• Do not invent citations or references.
• Do not invent approvals or final decisions.
• Use TODO when context is missing.
• Preserve human review checkpoints.
• Treat generated architecture outputs as drafts until reviewed.

🛠️ Package Notes

The CLI uses Node.js standard library only and has no runtime dependencies.

The npm package is published as @dilankam/architecture-knowledge.

The binary exposed by the package is architecture-knowledge.

Version publishing starts from packages/architecture-knowledge/package.json.

On main, CI automatically resolves the next available patch version for the current major.minor line before publishing.

Build the package knowledge snapshot before packing or publishing:

npm run build:knowledge