# Sa Brownfield Extract

> SA extract-mode procedure for brownfield onboarding Stage 2. Use when Solution Architect is dispatched in `extract` mode before SRS exists to turn Codebase Archaeologist reports and existing code/docs into a provisional docs/architecture.md with Source: extracted and confidence tags, plus extracted API/message contract stubs, route/dependency/async workflow coverage, and confirmation-pending open…

- **Type:** Skill
- **Install:** `agentstack add skill-evolplus-talos-sa-brownfield-extract`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [evolplus](https://agentstack.voostack.com/s/evolplus)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [evolplus](https://github.com/evolplus)
- **Source:** https://github.com/evolplus/talos/tree/main/skills/sa-brownfield-extract

## Install

```sh
agentstack add skill-evolplus-talos-sa-brownfield-extract
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# SA Brownfield Extract

## Use

Use this skill only for SA `extract` mode during brownfield onboarding Stage 2. The output documents what exists; it does not recommend changes.

## Inputs

- `docs/archaeology-reports/.md`
- Existing codebase/docs named by the report
- Optional `scope:` dispatch parameter: `architecture-only`, `security-compliance`, or a service/module name

## Outputs

- Provisional `docs/architecture.md`
- Observed-decision ADRs only when code irrefutably encodes the decision
- Extracted API/message contract stubs under `docs/api-contracts/` when endpoints, RPC operations, or messages are observable. Use service-level OpenAPI for REST, AsyncAPI for brokered messaging, proto for gRPC, GraphQL SDL for GraphQL, and markdown only for legacy/prototype surfaces with an explicit gap note.
- `docs/open-issues.md` entries with category `extract-confirmation-pending`
- Worktree `plan-update.json`

## Procedure

1. Read all archaeology reports for the scope. If any required report is `INSUFFICIENT`, halt and request more archaeology or team-interview input.
   - Before extracting, verify the report contains `## Service Boundary & Entry Point Map`, `## Route / RPC / Job Trace Matrix`, `## Dependency & Call Graph (C3)`, `## Message Broker / Consumer Logic`, and `## API / Message Spec Candidates` for the in-scope services.
   - If the project has public/internal APIs or brokered messages but those sections are missing or shallow, halt with `NEEDS_CONTEXT` and request a Stage 1 archaeology re-dispatch with deep route/dependency/contract scope. Do not compensate by writing vague architecture.
2. Map observed services/modules to C4 C1-C3:
   - C1/C2 are usually high confidence from repo layout, deploy manifests, and public surfaces.
   - C3 is package/module inferred; mark confidence honestly.
   - Do not extract C4 Code.
3. Populate architecture sections from observed evidence:
   - data models from migrations/ORM/schema files;
   - API inventory from Public API Surface + Service Boundary & Entry Point Map + API / Message Spec Candidates;
   - per-operation route trace from Route / RPC / Job Trace Matrix;
   - dependency/call graph from imports, clients, service registries, Route Trace rows, Dependency & Call Graph edges, and manifests;
   - async workflows from Message Broker / Consumer Logic, producers, consumers, topics, state transitions, retry/DLQ configs, and idempotency/dedup evidence;
   - cross-cutting concerns from middleware/config;
   - NFR posture from metrics when available, otherwise `unknown -- measure during pilot`.
4. For each discovered API/message, create an extracted contract stub with `Status: Extracted`, `Source: extracted`, confidence, observed auth, schemas, and TODO markers for non-introspectable fields.
   - REST: create or update `docs/api-contracts/.openapi.yaml` with `openapi: 3.1.0`, one operation per observed route, operationId, auth/security scheme, request/response schemas, observed status codes, standard error envelope, idempotency/rate-limit notes, and `x-source-evidence` file:line values.
   - gRPC: create or update `docs/api-contracts/.proto` with observed service/method/message shapes and TODO markers for unknown field types.
   - GraphQL: create or update `docs/api-contracts/.graphql` with observed query/mutation/subscription names, input/output types, auth notes, and TODO markers for unknown fields.
   - Async messaging: create or update `docs/api-contracts/.asyncapi.yaml` with `asyncapi: 2.6.0` or the project's declared version, channels, producer/consumer operation bindings, payload schemas, consumer groups, ack/commit behavior, retry/backoff/DLQ, idempotency/dedup, ordering/partition key, and side effects.
   - WebSocket/SSE: document as OpenAPI callbacks/webhooks when the project already uses OpenAPI that way; otherwise create a markdown extracted contract with connection/auth/message/event schemas and lifecycle states.
   - Never mark extracted contracts `Frozen`. FE Dev cannot consume them until BE Dev validates and freezes them during governed implementation or the human confirmation flow explicitly promotes them.
5. Tag every architecture section with `Source: extracted | Confidence: high|medium|low|inferred`.
6. File one open issue for every `Confidence: inferred` item.
7. Keep architecture self-contained. Do not put substantive body references back to archaeology reports or source paths.
8. Commit changes, then emit `plan-update.json`.

## Hard Rules

- Document what exists; do not recommend or redesign.
- Do not invent intent.
- Do not omit confidence tags.
- Do not propose new third-party dependencies.
- Do not write SRS or plan content.
- Do not collapse API/message contracts into prose-only architecture. If a route, RPC, or brokered message is observable, write a contract stub under `docs/api-contracts/` or halt with a named extraction gap.
- Do not treat a one-sided message observation as complete. A broker flow needs producer, payload, topic/queue, consumer handler, ack/commit, retry/DLQ, idempotency, and side effects when observable; unknown items become TODOs and open issues.
- Commit before signaling done.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [evolplus](https://github.com/evolplus)
- **Source:** [evolplus/talos](https://github.com/evolplus/talos)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-evolplus-talos-sa-brownfield-extract
- Seller: https://agentstack.voostack.com/s/evolplus
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.