Lintel on GitHub Copilot. Generated from skills/ta/SKILL.md; edit the canonical file, then run
li-copilot init.
- Resource root:
../../.. from this skill's base directory (the Lintel source with bin/,
lib/, skills/). Write plans, state and evidence into the working repository's .claude/
tree, never into the resource root.
- Skill-relative paths: this skill's own
scripts/, references/ and data/ folders (and a
<base> that the workflow defines as its own directory) mean
../../../skills/ta/ in the Lintel source, not this generated folder.
${LINTEL_SKILLS_DIR:-skills} means the skills root, ../../../skills. A bin/li-run step
runs in the working repository, so use $LINTEL_SKILLS_DIR/ta/ there.
- Shell steps: run Bash snippets with Bash (Git for Windows'
bash.exe on Windows, never
System32\bash.exe). Save a snippet to a temporary .sh file and run
bash "<resource root>/bin/li-run" <file>; it prepares LINTEL_SOURCE_ROOT, LINTEL_REPO_ROOT
and the profile context.
- Tools: Read=
view, Write=create, Edit=edit, Bash=bash/powershell, Grep=grep,
Glob=glob, AskUserQuestion=ask_user, TodoWrite=the plan checklist, Task or a named role=task
with that custom agent, WebFetch=web_fetch.
- Other Lintel workflows are native skills: invoke
/li-<name> rather than reading their
files. Named roles such as CodeReviewer are custom agents.
Technical architecture
What this module does
Produces architecture-grade decisions and contracts when work has architectural depth. Three granularities — full pass for new projects, loop iteration for refinement, single action for targeted ops.
For invariant/topology choices, failure isolation, tail-latency composition and capacity
assumptions, read architecture decision methods.
| Entry |
When |
Outputs |
/li-ta full |
new project / major scope change |
system-arch.md + ADR set + interface contracts + dependency graph + non-functional requirements |
/li-ta loop |
mid-cycle architecture iteration |
revised ADRs + diff against prior decisions + impact analysis |
/li-ta <capability> · /li-ta single --action <capability> |
targeted operation (see Sub-capability dispatch) |
one artifact per the dispatch table below |
When to use
- New service, API, dependency restructure, cross-system boundary
- Operator wants explicit architectural decisions documented as ADRs
- The active workflow explicitly requests architectural depth; no automatic hook dispatch is implied
- Work requires architecture-grade artifacts
When NOT to use
- Bug fix, small refactor, single-file change → use
/li-cycle --mode hotfix
- Data-model work without architectural impact → use
/li-da
- Pure observability/deployment work → use
/li-dh
Sub-capability dispatch
The seven capabilities remain direct entry points, not separate skills. Read the
named role from the trusted source and use the actual host's delegation operation
or an explicit serial handoff. The caller persists returned artifacts under the
selected attempt through the shared procedure required in Workflow below.
| Capability |
Dispatches to (agents) |
Produces |
Raise-help / notes |
api-design |
APIDesigner |
REST/GraphQL/gRPC interface spec with versioning + breaking-change analysis |
prefs: api_style, versioning; validation checklist below |
dependency-graph |
Explorer + Architect |
module dependency map + graph.dot, circular-detection, layering audit |
use project manifest clues below; distinguish static edges from observed runtime dependencies |
boundary-review |
Architect (BackendArchitect compatible entrypoint; choose one) |
bounded-context drift and failure-isolation report |
reuse dependency evidence only when its relevant input identity is unchanged; request SystemArchitect explicitly for an invariant/NFR question |
complexity-audit |
Architect |
per-component cyclomatic + cognitive scoring and refactor options |
obtain actual project budgets or label exploratory measurements advisory; report tool/version and excluded files |
scaling-plan |
CapacityPlanner; conditional Architect or BackendArchitect for an unresolved boundary |
capacity model, ranked bottlenecks and priced/qualitative projection |
target and baseline come from the brief; reuse existing boundary evidence, not a second default design pass; missing measurements remain unknown |
contract-collision |
APIDesigner + Architect |
impact across actual consumer versions and migration options |
requires named interface/change; even one mandatory consumer break needs a decision; no universal deprecation window |
quality-attributes |
SystemArchitect + Architect |
non-functional requirement spec + verification path per NFR |
backs the non_functionals_specified checkpoint; dims: latency p50/p95/p99 per journey, throughput RPS, error-rate %, availability SLA, observability signals per component |
Architect and BackendArchitect consume one distributed-boundary method from the
reference above. A name chosen by the operator remains valid; the table does not
dispatch both aliases for one result. Send exact original work/leaf IDs, topology
revision, existing analysis and the unresolved question to any distinct specialist.
api-design — invariant and consumer checks
complexity-audit — available analysis
Inspect project manifests and installed analyzer documentation/version before
selecting a command. Use only an available, authorized analyzer with a metric and
language scope that answer the question; do not install a guessed tool or invoke
a package-fetching runner by default. Record command, version, exclusions and the
applicable budget. Missing analyzer/output is unverified; source inspection may
support an explicitly advisory assessment, not measured complexity.
dependency-graph — project manifest clues
package.json → node · go.mod → go · Cargo.toml → rust ·
pyproject.toml/requirements.txt → python · pom.xml/build.gradle → jvm · *.csproj/*.sln → dotnet
Workflow
Read and execute the shared module caller procedure
before domain work. It is the sole owner of original work/package/leaf admission,
live P07/policy checks, immutable obligations, checkpoint publication, cold continuation
and final QA/independent acceptance. Apply the following architecture method inside
that procedure, not as a substitute for it.
- Select
full, an explicitly saved loop, or one named capability/single --action.
Unknown capability or absent saved iteration is NEEDS_CONTEXT, not a new guessed run.
- Start from the observable invariant and its writer/transaction/retry boundaries.
Trace dependencies and consumers before choosing topology. Preserve existing API
style/framework, accepted ADRs and actual optional preference data using the
preference metadata clarification.
The
engineering.tech_architecture.* hint is not a validated pack interface;
explicit invocation advice does not replace policy.
- Use the capability and checkpoint tables to compare alternatives, failure
isolation, deadlines, capacity assumptions and consumer transitions. Explorer
locates; Architect synthesizes/designs; independent reviewers assess, not repair.
Missing measurements remain unverified, not invented budget compliance.
Checkpoint ownership
| Checkpoint |
Method and receiver |
Artifact and observable acceptance |
discovery_complete |
Explorer evidence lookup, then Architect dependency synthesis |
dependency graph + consumer registry; distinguish observed edges, dynamic unknowns and intentional cycles |
decision_documented |
Architect/BackendArchitect options; ADRDrafter proposed record |
viable alternatives, invariant, decision owner and downside; proposed is not accepted |
contract_locked |
APIDesigner contract, actual consumer-version verification |
OpenAPI/SDL/protobuf + migration/notification evidence where required; additive is consumer-specific |
complexity_within_budget |
Architect interprets actual analyzer output |
measured scope/tool, applicable budget and bounded refactor recommendation; no metric-only rewrite |
non_functionals_specified |
SystemArchitect constraints, Architect fit |
NFR/invariant spec with source, workload, boundary and verification path; no sum of component p99s |
For loop, compare the selected prior ADRs/contracts and changed dependencies; retain
old artifacts and revisit affected checkpoints with new input identity. Returning
to a checkpoint never restores source files. For single API design, do not perform
a capacity sweep unless its unresolved requirement truly depends on it.
Advisory six-dimensional rubric
| Dimension | Score 0-100 |
|---|---|
| Decisions documented (ADR coverage) | <D1> |
| Contracts locked (interfaces signed + versioned) | <D2> |
| Complexity within budget | <D3> |
| Non-functionals specified | <D4> |
| Consumer impact analyzed | <D5> |
| Alternatives considered | <D6> |
Record each score's evidence and untested coverage. Any applicable mandatory
failure/error/unverified control blocks regardless of scores or operator preference.
Use the observable checkpoint criteria above, citing the actual artifact and missing
evidence. A checklist count alone is not calibrated architectural quality.
Handoff and recovery
Return named architecture artifacts, exact original work/profile/attempt references,
control/evidence links, advisory scores, limitations and next owner. Use the shared
start/result publication and cold-continuation table. Interrupted/failed output stays
visible. An audit record is optional observation unless policy explicitly requires it;
then verify real persistence without claiming it grants acceptance.
Reusable patterns
Follow the reusable pattern consumer contract.
Module entry resolves the architecture expectations bound to the current target context and
passes each sub-capability only its projected clauses (project for the mapped package, or the
clauses mapped to it). An unknown deployment target or platform yields needs-context and
blocks the dependent design; no live cloud, tenant or environment discovery is implied, and
requirements are never inferred from generic recommendations. When the runtime reports no
patterns, the module is unchanged.
Status protocol
- DONE — selected results, required checks and independent acceptance complete
- DONE_WITH_CONCERNS — required gates pass; remaining concerns are advisory only
- BLOCKED — required checkpoint/evidence/policy/review failed or unavailable
- NEEDS_CONTEXT — unknown capability for single, OR no prior state for loop
Integration
Reads:
- Original mapped artifacts and pinned pack fields; explicit advisory inputs, no automatic personal preference read
lib/pack-resolver.sh for pack policy
- Architecture roles: Architect, BackendArchitect, APIDesigner, SystemArchitect, CapacityPlanner
- Existing ADRs in the repository's declared decision location
Writes:
- Selected
system-arch.md, interface/ADR/NFR artifacts and iteration comparison;
runtime start/result files under .claude/runtime/state/domains/<operation>/iNNNN/.
- Existing
state/ta/ artifacts remain usable only when explicitly selected and verified.
- Brief Forge only when explicitly invoked/configured; no automatic hook activation
Triggered by:
- Operator:
/li-ta {full|loop|single --action <name>}
- BUILD phase: invokes as sub-module when architectural intent detected
/li-full-engineering-pass: first module in the composition DAG
Hooks (dormant by decision, ADR-0008 — ship in hooks/shared/ but are opt-in, not auto-registered):
hooks/shared/ta-arch-drift-warn/ (pre-edit on ADR-claimed files)
hooks/shared/ta-contract-collision-warn/ (pre-edit on interface files)
hooks/shared/ta-complexity-budget-warn/ (pre-commit)
These optional warnings are unobserved unless actual host registration and execution
are evidenced. They neither supply architectural measurements nor clear a required gate.
Anti-patterns
- Skipping single granularity to "be safe" — single is the operator's explicit choice; honor it
- Treating checkpoint failure as terminal — checkpoints surface, recover, continue
- Inventing new agents when existing ones cover — Architect/BackendArchitect/APIDesigner cover most TA work; new agents only for genuinely new capability
- Hardcoding api_style / versioning — use actual verified pack fields or explicit advisory inputs
- Silent score-below-threshold — surface to operator with dimension breakdown; never auto-pass
- Confusing a warn-hook with policy — advisory warnings are not enforced controls;
applicable mandatory requirements still block independently of the warning mechanism
1---2name: li-ta3description: Use for technical-architecture depth — service boundaries, API contracts, dependency graphs, scaling plans, complexity audits, and quality attributes. Reach for it when a design needs architectural rigor beyond what PLAN gives. Runs full, loop, or single-capability, dispatching to the architecture agents and scoring against a rubric.4metadata:5 source: https://skillmd.com/skills/jokerman89/li-ta6---78> **Lintel on GitHub Copilot.** Generated from `skills/ta/SKILL.md`; edit the canonical file, then run9> `li-copilot init`.10> - **Resource root:** `../../..` from this skill's base directory (the Lintel source with `bin/`,11> `lib/`, `skills/`). Write plans, state and evidence into the working repository's `.claude/`12> tree, never into the resource root.13> - **Skill-relative paths:** this skill's own `scripts/`, `references/` and `data/` folders (and a14> `<base>` that the workflow defines as its own directory) mean15> `../../../skills/ta/` in the Lintel source, not this generated folder.16> `${LINTEL_SKILLS_DIR:-skills}` means the skills root, `../../../skills`. A `bin/li-run` step17> runs in the working repository, so use `$LINTEL_SKILLS_DIR/ta/` there.18> - **Shell steps:** run Bash snippets with Bash (Git for Windows' `bash.exe` on Windows, never19> `System32\bash.exe`). Save a snippet to a temporary `.sh` file and run20> `bash "<resource root>/bin/li-run" <file>`; it prepares `LINTEL_SOURCE_ROOT`, `LINTEL_REPO_ROOT`21> and the profile context.22> - **Tools:** Read=`view`, Write=`create`, Edit=`edit`, Bash=`bash`/`powershell`, Grep=`grep`,23> Glob=`glob`, AskUserQuestion=`ask_user`, TodoWrite=the plan checklist, Task or a named role=`task`24> with that custom agent, WebFetch=`web_fetch`.25> - **Other Lintel workflows** are native skills: invoke `/li-<name>` rather than reading their26> files. Named roles such as `CodeReviewer` are custom agents.2728# Technical architecture2930## What this module does3132Produces architecture-grade decisions and contracts when work has architectural depth. Three granularities — full pass for new projects, loop iteration for refinement, single action for targeted ops.3334For invariant/topology choices, failure isolation, tail-latency composition and capacity35assumptions, read [architecture decision methods](../../../skills/ta/references/decision-methods.md).3637| Entry | When | Outputs |38|---|---|---|39| `/li-ta full` | new project / major scope change | `system-arch.md` + ADR set + interface contracts + dependency graph + non-functional requirements |40| `/li-ta loop` | mid-cycle architecture iteration | revised ADRs + diff against prior decisions + impact analysis |41| `/li-ta <capability>` · `/li-ta single --action <capability>` | targeted operation (see Sub-capability dispatch) | one artifact per the dispatch table below |4243## When to use4445- New service, API, dependency restructure, cross-system boundary46- Operator wants explicit architectural decisions documented as ADRs47- The active workflow explicitly requests architectural depth; no automatic hook dispatch is implied48- Work requires architecture-grade artifacts4950## When NOT to use5152- Bug fix, small refactor, single-file change → use `/li-cycle --mode hotfix`53- Data-model work without architectural impact → use `/li-da`54- Pure observability/deployment work → use `/li-dh`5556## Sub-capability dispatch5758The seven capabilities remain direct entry points, not separate skills. Read the59named role from the trusted source and use the actual host's delegation operation60or an explicit serial handoff. The caller persists returned artifacts under the61selected attempt through the shared procedure required in Workflow below.6263| Capability | Dispatches to (agents) | Produces | Raise-help / notes |64|---|---|---|---|65| `api-design` | APIDesigner | REST/GraphQL/gRPC interface spec with versioning + breaking-change analysis | prefs: `api_style`, `versioning`; validation checklist below |66| `dependency-graph` | Explorer + Architect | module dependency map + `graph.dot`, circular-detection, layering audit | use project manifest clues below; distinguish static edges from observed runtime dependencies |67| `boundary-review` | Architect (BackendArchitect compatible entrypoint; choose one) | bounded-context drift and failure-isolation report | reuse dependency evidence only when its relevant input identity is unchanged; request SystemArchitect explicitly for an invariant/NFR question |68| `complexity-audit` | Architect | per-component cyclomatic + cognitive scoring and refactor options | obtain actual project budgets or label exploratory measurements advisory; report tool/version and excluded files |69| `scaling-plan` | CapacityPlanner; conditional Architect or BackendArchitect for an unresolved boundary | capacity model, ranked bottlenecks and priced/qualitative projection | target and baseline come from the brief; reuse existing boundary evidence, not a second default design pass; missing measurements remain unknown |70| `contract-collision` | APIDesigner + Architect | impact across actual consumer versions and migration options | requires named interface/change; even one mandatory consumer break needs a decision; no universal deprecation window |71| `quality-attributes` | SystemArchitect + Architect | non-functional requirement spec + verification path per NFR | backs the `non_functionals_specified` checkpoint; dims: latency p50/p95/p99 per journey, throughput RPS, error-rate %, availability SLA, observability signals per component |7273Architect and BackendArchitect consume one distributed-boundary method from the74reference above. A name chosen by the operator remains valid; the table does not75dispatch both aliases for one result. Send exact original work/leaf IDs, topology76revision, existing analysis and the unresolved question to any distinct specialist.7778### api-design — invariant and consumer checks7980- [ ] Name the invariant, authoritative writer and transaction boundary before choosing endpoints or topology.81- [ ] Define method/path, request/response/error schema and allowed state transitions in the applicable OpenAPI/Protobuf/SDL contract.82- [ ] Check actual consumer versions and migration needs even for a first-version or nominally additive change.83- [ ] Bind authentication and object/tenant authorization to the protected action, not merely a noted mechanism.84- [ ] Define idempotency, end-to-end deadlines, retry ownership and overload/quota behavior from actual requirements.85- [ ] Give representative payloads and observable failure cases for duplicate effects, partial completion and consumer compatibility.8687### complexity-audit — available analysis8889Inspect project manifests and installed analyzer documentation/version before90selecting a command. Use only an available, authorized analyzer with a metric and91language scope that answer the question; do not install a guessed tool or invoke92a package-fetching runner by default. Record command, version, exclusions and the93applicable budget. Missing analyzer/output is unverified; source inspection may94support an explicitly advisory assessment, not measured complexity.9596### dependency-graph — project manifest clues9798`package.json` → node · `go.mod` → go · `Cargo.toml` → rust ·99`pyproject.toml`/`requirements.txt` → python · `pom.xml`/`build.gradle` → jvm · `*.csproj`/`*.sln` → dotnet100101## Workflow102103Read and execute the [shared module caller procedure](../../../skills/full-engineering-pass/references/domain-handoff.md#module-caller-procedure)104before domain work. It is the sole owner of original work/package/leaf admission,105live P07/policy checks, immutable obligations, checkpoint publication, cold continuation106and final QA/independent acceptance. Apply the following architecture method inside107that procedure, not as a substitute for it.1081091. Select `full`, an explicitly saved `loop`, or one named capability/`single --action`.110 Unknown capability or absent saved iteration is NEEDS_CONTEXT, not a new guessed run.1112. Start from the observable invariant and its writer/transaction/retry boundaries.112 Trace dependencies and consumers before choosing topology. Preserve existing API113 style/framework, accepted ADRs and actual optional preference data using the114 [preference metadata clarification](../../../skills/da/references/preferences.md).115 The `engineering.tech_architecture.*` hint is not a validated pack interface;116 explicit invocation advice does not replace policy.1173. Use the capability and checkpoint tables to compare alternatives, failure118 isolation, deadlines, capacity assumptions and consumer transitions. Explorer119 locates; Architect synthesizes/designs; independent reviewers assess, not repair.120 Missing measurements remain unverified, not invented budget compliance.121122## Checkpoint ownership123124| Checkpoint | Method and receiver | Artifact and observable acceptance |125|---|---|---|126| `discovery_complete` | Explorer evidence lookup, then Architect dependency synthesis | dependency graph + consumer registry; distinguish observed edges, dynamic unknowns and intentional cycles |127| `decision_documented` | Architect/BackendArchitect options; ADRDrafter proposed record | viable alternatives, invariant, decision owner and downside; proposed is not accepted |128| `contract_locked` | APIDesigner contract, actual consumer-version verification | OpenAPI/SDL/protobuf + migration/notification evidence where required; additive is consumer-specific |129| `complexity_within_budget` | Architect interprets actual analyzer output | measured scope/tool, applicable budget and bounded refactor recommendation; no metric-only rewrite |130| `non_functionals_specified` | SystemArchitect constraints, Architect fit | NFR/invariant spec with source, workload, boundary and verification path; no sum of component p99s |131132For `loop`, compare the selected prior ADRs/contracts and changed dependencies; retain133old artifacts and revisit affected checkpoints with new input identity. Returning134to a checkpoint never restores source files. For single API design, do not perform135a capacity sweep unless its unresolved requirement truly depends on it.136137### Advisory six-dimensional rubric138139```140| Dimension | Score 0-100 |141|---|---|142| Decisions documented (ADR coverage) | <D1> |143| Contracts locked (interfaces signed + versioned) | <D2> |144| Complexity within budget | <D3> |145| Non-functionals specified | <D4> |146| Consumer impact analyzed | <D5> |147| Alternatives considered | <D6> |148149Record each score's evidence and untested coverage. Any applicable mandatory150failure/error/unverified control blocks regardless of scores or operator preference.151```152153Use the observable checkpoint criteria above, citing the actual artifact and missing154evidence. A checklist count alone is not calibrated architectural quality.155156### Handoff and recovery157158Return named architecture artifacts, exact original work/profile/attempt references,159control/evidence links, advisory scores, limitations and next owner. Use the shared160start/result publication and cold-continuation table. Interrupted/failed output stays161visible. An audit record is optional observation unless policy explicitly requires it;162then verify real persistence without claiming it grants acceptance.163164## Reusable patterns165166Follow the [reusable pattern consumer contract](../../../skills/pattern/references/consumer-contract.md).167Module entry resolves the architecture expectations bound to the current target context and168passes each sub-capability only its projected clauses (`project` for the mapped package, or the169clauses mapped to it). An unknown deployment target or platform yields `needs-context` and170blocks the dependent design; no live cloud, tenant or environment discovery is implied, and171requirements are never inferred from generic recommendations. When the runtime reports no172patterns, the module is unchanged.173174## Status protocol175176- **DONE** — selected results, required checks and independent acceptance complete177- **DONE_WITH_CONCERNS** — required gates pass; remaining concerns are advisory only178- **BLOCKED** — required checkpoint/evidence/policy/review failed or unavailable179- **NEEDS_CONTEXT** — unknown capability for single, OR no prior state for loop180181## Integration182183**Reads:**184- Original mapped artifacts and pinned pack fields; explicit advisory inputs, no automatic personal preference read185- `lib/pack-resolver.sh` for pack policy186- Architecture roles: Architect, BackendArchitect, APIDesigner, SystemArchitect, CapacityPlanner187- Existing ADRs in the repository's declared decision location188189**Writes:**190- Selected `system-arch.md`, interface/ADR/NFR artifacts and iteration comparison;191 runtime start/result files under `.claude/runtime/state/domains/<operation>/iNNNN/`.192- Existing `state/ta/` artifacts remain usable only when explicitly selected and verified.193- Brief Forge only when explicitly invoked/configured; no automatic hook activation194195**Triggered by:**196- Operator: `/li-ta {full|loop|single --action <name>}`197- BUILD phase: invokes as sub-module when architectural intent detected198- `/li-full-engineering-pass`: first module in the composition DAG199200**Hooks** (dormant by decision, ADR-0008 — ship in `hooks/shared/` but are opt-in, not auto-registered):201- `hooks/shared/ta-arch-drift-warn/` (pre-edit on ADR-claimed files)202- `hooks/shared/ta-contract-collision-warn/` (pre-edit on interface files)203- `hooks/shared/ta-complexity-budget-warn/` (pre-commit)204205These optional warnings are unobserved unless actual host registration and execution206are evidenced. They neither supply architectural measurements nor clear a required gate.207208## Anti-patterns209210- **Skipping single granularity to "be safe"** — single is the operator's explicit choice; honor it211- **Treating checkpoint failure as terminal** — checkpoints surface, recover, continue212- **Inventing new agents when existing ones cover** — Architect/BackendArchitect/APIDesigner cover most TA work; new agents only for genuinely new capability213- **Hardcoding api_style / versioning** — use actual verified pack fields or explicit advisory inputs214- **Silent score-below-threshold** — surface to operator with dimension breakdown; never auto-pass215- **Confusing a warn-hook with policy** — advisory warnings are not enforced controls;216 applicable mandatory requirements still block independently of the warning mechanism