Legacy friendly contextualisation: Describe -> Discover -> Unify -> Spec

[rafaelcalves]

I loved the way Agent-OS guides the user through the process of discovering standards but I missed a command to really gather existing information about a legacy project that needs contextualisation.

I've designed this tools to implement agent-os like features on a legacy system. I'm sharing it to maybe incorporate them into a new version:

https://github.com/rafaelcalves/agent-discovery-tools

Overview

The toolkit consists of four core skills that should be executed in order:

#	Skill	Purpose	Output
1	Describe Architecture	Document what each service does, its tech stack, and integrations	AGENTS.md + ARCHITECTURE.md per module
2	Discover Standards	Extract tribal knowledge and coding patterns from the codebase	.agents/rules/standards/ per module
3	Unify Standards	Merge per-module standards into shared, org-wide rules	Root .agents/rules/standards/
4	Shape Spec	Plan new features using all gathered context	.agents/local/specs/

Each skill builds on the output of the previous one — describe gives the AI context about what exists, discover captures how your team writes code, unify promotes the best patterns across projects, and shape leverages all of that to plan new work.

---

Simplified View (Linear)

For a quick mental model, the flow is:

Describe → Discover → Unify → Shape → Implement
   ↑           ↑         ↑        ↑
   └───────────┴─────────┴────────┘
        Jira + Confluence + Codebase

---

The Four Core Skills

1. Describe Architecture

What it does: Generates AGENTS.md (agent configuration) and ARCHITECTURE.md (technical documentation) for each microservice/module by analyzing code and pulling context from Confluence and Jira.

When to run: First. Run once per module to establish a baseline.

Trigger phrases:

• "describe architecture"
• "document microservice"
• "generate AGENTS.md for order-service"

What it produces:

service-a/
└── .agents/
    ├── AGENTS.md           # Jira config, Confluence refs, overview, output preferences
    └── memories/
        └── ARCHITECTURE.md # Tech stack, package structure, APIs, data flow, deployment

2. Discover Standards

What it does: Reads representative code files in a focus area (API, domain, testing, etc.), identifies patterns that are unusual, opinionated, or tribal, and writes them as concise standard files.

When to run: After describe. Run per module, per focus area.

Trigger phrases:

• "discover standards"
• "find coding standards in order-service"
• "extract conventions"

What it produces:

service-a/
└── .agents/
    └── rules/
        └── standards/
            ├── index.yml
            ├── api/
            │   └── response-envelope.md
            ├── domain/
            │   └── immutable-models.md
            └── testing/
                └── wiremock-pattern.md

3. Unify Standards

What it does: Scans all per-module standards, scores them by usage/simplicity/distinctiveness, groups similar rules across projects, and merges them into shared org-wide standards at the root level.

When to run: After you've discovered standards in at least 2+ modules.

Trigger phrases:

• "unify standards"
• "merge rules"
• "consolidate standards"

What it produces:

your-project/
└── .agents/
    └── rules/
        └── standards/          # root-level unified standards
            ├── index.yml
            ├── api/
            │   └── structured-logging.md
            ├── domain/
            │   └── immutable-domain-models.md
            └── testing/
                └── wiremock-external-apis.md

4. Shape Spec

What it does: Gathers context from .agents/ directories, Jira, and Confluence to plan and structure a feature spec before implementation begins. Reads architecture docs, relevant standards, and reference implementations to create an actionable plan.

When to run: When starting significant new work. Requires plan mode in Copilot.

Trigger phrases:

• "shape spec"
• "plan feature"
• "shape this work"

What it produces:

your-project/
└── .agents/
    └── local/
        └── specs/
            └── PROJ-1234-user-comments/
                ├── plan.md         # Full implementation plan
                ├── shape.md        # Scope, decisions, context
                ├── context.md      # Gathered from .agents/, Jira, Confluence
                ├── standards.md    # Applicable standards
                ├── references.md   # Similar code pointers
                └── visuals/        # Mockups (if any)

---