agentsclimarketplace

Architect design feature

Skill pappar/hitl-claude-plugin/skills/architect-design-feature

Orchestrate the architect's design journey for a change — steps 3 through 9. Covers impact analysis, HLD and LLD generation with approval gates, slice decomposition, test case planning, and decision packet assembly. Produces decision packets ready to hand to developers. Do not invoke spontaneously; requires a GitHub issue.From its SKILL.md

Install
npx -y skills add pappar/hitl-claude-plugin --skill architect-design-feature

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
  • 3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

19.8 KB, as published. Nobody here has run it

Design Feature — Architect Workflow (Steps 3–9)

Input: $ARGUMENTS (GitHub issue number and/or feature description)

Refusal rule: If no GitHub issue number is provided or discoverable, stop and say: "No GitHub issue found. Create one first with gh issue create, then re-run with the issue number."


Startup — Status Router

Before doing anything else, check .hitl/current-change.yaml:

[ -f .hitl/current-change.yaml ] && grep "^status:" .hitl/current-change.yaml || echo "status: not-found"

Route based on the current status:

StatusAction
File not foundProceed normally — run from Phase 1
planningProceed normally — run from Phase 1
awaiting-scope-approvalOutput the gate-pending message below and STOP
scope-approvedSkip to Phase 3 (HLD)
awaiting-hld-approvalOutput the gate-pending message below and STOP
hld-approvedSkip to Phase 5 (LLD)
awaiting-lld-approvalOutput the gate-pending message below and STOP
lld-approvedSkip to Phase 10 (Decision Packet)
awaiting-packet-approvalOutput the gate-pending message below and STOP
implementation-approvedOutput: "Design is complete. Decision packets are ready — hand them to developers to begin /hitl:dev-tdd." and STOP
blockedOutput the blocked message below and STOP

Gate-pending message (for any awaiting-* status):

Gate pending — waiting for TA approval.

Status:   [current status]
Change:   [change_id]

The TA must run /hitl:ta-approve to review the current artifact and advance this gate.
Once approved, re-run this command to continue to the next phase.

Blocked message (for blocked status):

This change is blocked — a gate was rejected by the TA.

Gate:     [blocker.gate]
Finding:  [blocker.finding]

Address the finding above, then re-run this command. The skill will resume
at the rejected phase so you can rework the artifact.

For blocked status: after showing the blocked message, ask the architect: "Are you ready to rework the [blocker.gate] artifact? Say 'yes' to resume." On confirmation, clear the blocked status and route to the appropriate phase to re-do that work.


Graphify pre-flight: Before the first step, run:

[ -f graphify-out/graph.json ] && echo "Graphify: available" || echo "Graphify: unavailable"

State the result once — "✅ Graphify available, using graph queries" or "⚠️ Graphify unavailable — using direct doc reads throughout." Apply that result for every step; do not rediscover availability mid-task.


Progress Banners

Output the banner for the current phase at the start of every phase — before any questions, analysis, or content. Format: --- line, **Design Feature — Phase N / 10: [Name]**, trail, ---.

See progress-banners.md for the full per-phase banner-trail table.


Phase 1 — Impact Analysis and Scope (Step 3)

1a. Read and challenge the issue

Fetch the GitHub issue from $ARGUMENTS. Extract: title, description, any linked Figma references.

Detect project type and locate the requirements source:

  • Migration project — if docs/00-migration/migration-brief.md exists, that file is the requirements source. It replaces docs/01-product/prd.md. Read it in full. The issue title should reference the migration slice being designed; the migration brief is the source of truth for acceptance criteria and NFRs. Do not look for an FR-<ID> pointer — migration slices reference MR-<ID> from the brief instead.
  • Standard project — extract the PRD reference (FR-<ID>) from the issue and read docs/01-product/prd.md at that requirement. The issue is a pointer; the PRD is the source of truth.

Before reading the manifest or doing any analysis, challenge the issue against its requirements source:

  1. Is the problem statement specific? If the issue says "users want X" or "improve Y" without data, ask: "What evidence supports this — support tickets, analytics, churn feedback, user research?" For migration: "What in the migration brief or external reference docs supports this slice being needed now?"
  2. Are the acceptance criteria testable? Vague AC ("should feel fast", "user-friendly") cannot drive an LLD or tests. Ask for specific, measurable criteria before proceeding.
  3. Are NFRs relevant to this change stated? If the change affects throughput, latency, or availability, are the targets in the issue or findable in the requirements source? If not, ask — see ${CLAUDE_PLUGIN_ROOT}/shared/challenge-stance.md for the full NFR checklist.
  4. Is the proposed solution the right solution? State the problem, then ask: "Is there a simpler approach that would solve the same problem?" If yes, name it and the tradeoff before designing the proposed solution.

If any answer is unsatisfactory, resolve it now — not after the HLD is generated.

1b. Read the system manifest

Prefer a graph query:

/graphify query "all domains and facade APIs"
/graphify query "domain: <candidate-domain> facade APIs boundary entities"

Fall back to reading docs/system-manifest.yaml directly if Graphify is unavailable.

1c. Check past incidents in candidate domains

/graphify query "past incidents affecting domain: <domain-name>"

Fall back to reading docs/04-operations/incident-registry.yaml directly.

1d. Identify the affected scope

From the issue and manifest, determine:

  • Affected domains — which manifest domains must change?
  • Affected facade APIs — which public contracts change or get added?
  • Affected boundary entities — which shared data types change shape?
  • IaC changes — are infrastructure, migrations, configs, or secrets required?
  • Backwards compatibility — does any facade API or boundary entity change break existing callers?

If backwards-incompatible changes are identified, flag them explicitly. Do not proceed without a compatibility strategy.

1e. Determine the tier

Use the tier definitions from ${CLAUDE_PLUGIN_ROOT}/skills/dev-practices/SKILL.md. State the tier with justification.

Challenge the tier before accepting it:

  • Cross-domain or multi-service changes are Tier 3 even when described as simple
  • If the change touches more than one domain AND those domains have ordering dependencies, confirm whether this should be split into sequential changes
  • If the change is too large for one slice, say so and wait for architect confirmation before proceeding

1f. Estimate effort and token cost

Estimate implementation effort (in days) based on the number of affected domains, facade API changes, and IaC scope. This determines whether step 4 (ROI) is required.

For token cost estimation, use the phase-level formula from ${CLAUDE_PLUGIN_ROOT}/skills/dev-practices/roi-estimation.md.

1g. Initialize .hitl/current-change.yaml

Create or update using the schema at ${CLAUDE_PLUGIN_ROOT}/shared/templates/change-context.schema.yaml. See ${CLAUDE_PLUGIN_ROOT}/shared/templates/GH-000-example.yaml for a filled-in example.

Set from this impact analysis:

  • change_id: GH-<issue-number>
  • tier: from Step 1e
  • status: planning
  • source_artifacts.issue: GitHub issue URL; set hld and lld to pending
  • manifest.domain: primary affected domain
  • allowed_paths: source paths for all affected domains
  • approvals.product and approvals.architecture: both pending
  • token_tracking.estimated: populate with the cost estimate from Step 1f

1h. Gate — architect confirms scope

Present the impact summary:

## Impact Summary — GH-<N>: [title]
Tier: N | Effort estimate: N days

Affected domains:     [list]
Facade API changes:   [list or "none"]
Boundary entity changes: [list or "none"]
IaC changes:          [list or "none"]
Backwards compat:     [compatible / incompatible — details]
Incident history:     [relevant incidents or "none found"]
ROI required:         [yes — effort > 1 day / no]

Update .hitl/current-change.yaml: set status: awaiting-scope-approval.

Post a GitHub issue comment:

gh issue comment <issue-number> \
  --body "## ⏸ Gate: Scope Review

Impact analysis complete. Awaiting TA approval before HLD generation begins.

**Tier:** [N] | **Effort:** [N days] | **Domains:** [list]
**Backwards compat:** [compatible / incompatible — details]

Run \`/hitl:ta-approve\` to review and advance this gate."

Output:

Gate 1 reached — status set to 'awaiting-scope-approval'.

The TA must run /hitl:ta-approve to confirm scope before HLD generation begins.
Re-run /hitl:architect-design-feature after TA approval to continue.

STOP. Do not generate any further content. This session ends here.


Phase 2 — ROI Trigger Check (Step 4)

If effort estimate exceeds 1 day:

Record the ROI section in .hitl/current-change.yaml under roi_estimate using the template in ${CLAUDE_PLUGIN_ROOT}/skills/dev-practices/roi-estimation.md. Fill in:

  • Value dimension
  • Expected outcome (specific, falsifiable, with timeframe)
  • Baseline metric placeholder (note: architect must measure this now, not estimate it)
  • Measurement plan
  • 30/90-day checkpoint dates

Present the draft to the architect. Ask them to fill in the baseline metric before proceeding — it cannot be estimated after the fact.

Post a pointer comment on the GitHub issue (not the content — the content lives in the context file and will be included in the decision packet at Phase 10):

gh issue comment <issue-number> --body "ROI estimate required — filed in decision packet (effort > 1 day)."

If effort estimate is ≤ 1 day, state: "ROI estimate not required — change is <1 day."


Phase 3 — HLD (Step 5, Part 1)

For Tier 2 and above:

  1. Generate the HLD at docs/02-design/technical/hld/<feature-name>.md following the instructions in Phase 1 of the generate-docs skill. The HLD must include:

    • Executive summary
    • System architecture diagram (Mermaid graph TB or graph LR)
    • Component overview table
    • Data flow diagrams (Mermaid sequenceDiagram)
    • Integration points with affected facade APIs
    • Security considerations
    • Any design decisions being made (flag each as a candidate ADR)
  2. Update docs/02-design/technical/hld/index.md.

  3. Update source_artifacts.hld in .hitl/current-change.yaml.

Update .hitl/current-change.yaml: set status: awaiting-hld-approval.

Post a GitHub issue comment:

gh issue comment <issue-number> \
  --body "## ⏸ Gate: HLD Review

High-Level Design is ready for TA review.

**HLD:** \`docs/02-design/technical/hld/<feature-name>.md\`

Run \`/hitl:ta-approve\` to review and advance this gate. The TA checklist covers:
component boundaries, security model, ADR candidates, and implementation bias."

Output:

Gate 2 reached — status set to 'awaiting-hld-approval'.

The TA must run /hitl:ta-approve to review the HLD before LLD generation begins.
Re-run /hitl:architect-design-feature after TA approval to continue.

STOP. Do not generate ADRs or LLDs. This session ends here.

For Tier 0–1: skip this phase.


Phase 4 — ADR Capture (Step 5, Part 2)

After HLD approval:

  1. From the approved HLD, identify every design decision — framework choice, pattern selection, tradeoff made, constraint accepted.

  2. For each decision that is not already documented in an existing ADR, create a stub at docs/02-design/technical/adrs/<decision-slug>.md using ${CLAUDE_PLUGIN_ROOT}/shared/templates/adr-template.md. Mark status as "DRAFT — architect to complete rationale."

  3. Ask the architect:

    "I've created stubs for [N] decisions I found in the HLD. Are there decisions being made here that aren't visible in the design — things the team discussed, constraints from legal or ops, or choices you ruled out?"

  4. Add any architect-supplied decisions as additional ADR stubs.

  5. Update source_artifacts.adr in .hitl/current-change.yaml with the ADR paths.


Phase 5 — LLD per Domain (Step 5, Part 3)

For each affected domain identified in Phase 1:

  1. Generate the LLD at docs/02-design/technical/lld/<domain>/<component>.md following the instructions in Phase 2 of the generate-docs skill. Each LLD must include:

    • Component purpose
    • Mermaid class diagram
    • Method signatures with parameters, return types, and preconditions
    • Sequence diagrams for non-trivial flows
    • Facade API surface that other domains call
    • Error modes and their handling
  2. Update docs/02-design/technical/lld/index.md.

  3. After each LLD is written, update source_artifacts.lld in .hitl/current-change.yaml.

  4. After ALL domain LLDs are written, update .hitl/current-change.yaml: set status: awaiting-lld-approval.

Post a GitHub issue comment:

gh issue comment <issue-number> \
  --body "## ⏸ Gate: LLD Review

Low-Level Designs are ready for TA review.

**Domains:** <domain list>
**LLD(s):** \`docs/02-design/technical/lld/...\`

Run \`/hitl:ta-approve\` to review and advance this gate. The TA checklist covers:
method signature precision, error modes completeness, HLD alignment, and slice demo answers."

Output:

Gate 3 reached — status set to 'awaiting-lld-approval'.

The TA must run /hitl:ta-approve to review the LLD(s) before slice decomposition begins.
Re-run /hitl:architect-design-feature after TA approval to continue.

STOP. Do not begin slice decomposition. This session ends here.


Phase 6 — IaC Planning (Step 6)

If Phase 1 identified IaC changes:

For each affected infrastructure artifact, specify:

  • File path (Terraform module, Kubernetes manifest, migration file, config)
  • What changes (resource added/modified/removed, migration direction, config key)
  • Whether the change is reversible

Config and secrets externalization (required):

For any new config or secret introduced by this change:

  • Config values must be externalized as environment variables or a config service reference — not hardcoded in source.
  • Secrets must be declared as vault references — never as literal values in IaC, migrations, or deploy scripts.

For each new secret, record the vault path and secret manager. If a secret has no vault path assigned, stop: "Secret <name> has no vault path. Assign one before proceeding."

Record the IaC plan in .hitl/current-change.yaml:

iac_plan:
  - path: <file>
    change: <description>
    reversible: true|false
secrets:
  - name: <SECRET_NAME>
    vault_path: <path>
    manager: <aws-secrets-manager|hashicorp-vault|gcp-secret-manager|azure-key-vault|ssm>

If no IaC changes: state "No IaC changes identified" and continue.


Phase 7 — Slice Decomposition

This is the architect's core parallelization decision.

7a. List the slices

Each slice must touch exactly one manifest domain. Present the candidate slices:

Proposed slice plan:
  Slice 1: domain [A] — [one-line description of what changes]
  Slice 2: domain [B] — [one-line description of what changes]
  ...

7b. Check for demoability

For each slice, answer: "What does the PM see at the end of this slice?"

A valid answer is one of:

  • A user-visible feature or workflow step the PM can exercise in the running app
  • A measurable outcome with a defined pass/fail (for infrastructure-only slices: record counts, latency comparison, error-rate delta)

If the answer is "nothing visible yet" — the slice is too narrow. Either extend it to include the user-visible layer, or merge it into an adjacent slice that completes the user-facing story.

Add a demo: line to each slice:

Slice 1: domain [A] — [description]
  Demo: PM can [specific action] and see [specific result]

7c. Check for domain independence

For each pair of slices, determine:

  • Do they share any mutable state, database tables, or external API contracts?
  • Does slice N depend on a schema or interface change introduced by slice M?
  • Could both slices be deployed to production independently without breaking anything?

If two slices are NOT independent:

  • State which ordering constraint exists
  • Mark them as sequential (complete and merge slice M before starting slice N)
  • Do not allow them to be handed to different developers concurrently

7d. Present the final slice plan

Slice plan — GH-<N>:
  Slice 1: domain [A] [PARALLEL OK]
    Developer: [to be assigned]
    LLD: docs/02-design/technical/lld/[A]/...
    Demo: PM can [specific action] and see [specific result]
  Slice 2: domain [B] [SEQUENTIAL — after Slice 1]
    Developer: [to be assigned]
    LLD: docs/02-design/technical/lld/[B]/...
    Demo: PM can [specific action] and see [specific result]

STOP. Ask the architect:

  • "Does each slice's Demo answer clearly describe what the PM will see?"
  • "Are these slices correctly domain-isolated?"
  • "Any hidden dependencies between slices I missed?"
  • "Confirm parallelism?"

Do not proceed until the architect confirms the slice plan.


Phase 8 — Test Case Planning (Step 7)

For each confirmed slice:

Using the approved LLD for that domain, produce a concrete test plan:

ActionTest nameWhat it covers
ADDtest_<scenario>[behavior from LLD]
UPDATEtest_<existing>[what changes]
REMOVEtest_<obsolete>[why no longer needed]
VERIFY (regression)test_<existing>[what must still pass]

Also check:

/graphify query "past incidents affecting domain: <domain-name>"

Fall back to docs/04-operations/incident-registry.yaml. For each relevant incident, add a regression test to the plan.

Record the test plan in .hitl/current-change.yaml under tests.plan (one entry per slice).

Ask the architect: "Is the test plan complete? Anything from domain knowledge or past incidents that should be covered but isn't here?"


Phase 9 — Training Plan Stub (Step 8, conditional)

Check if the change introduces any of:

  • A new architectural pattern not already present in the codebase
  • A new external system integration
  • A new framework or primitive
  • A new ML/AI technique
  • A refactor that significantly changes how engineers reason about a subsystem

If yes: create a stub at docs/03-engineering/training/<capability>.md using ${CLAUDE_PLUGIN_ROOT}/shared/templates/training-plan-template.md. Link to the relevant LLDs and ADRs. Mark sections as "DRAFT — architect to complete."

If no: state the reason explicitly (e.g., "No training plan required — this extends an existing pattern.").


Phase 10 — Decision Packet Assembly (Step 9)

For each confirmed slice, create one decision packet under docs/decisions/. See decision-packet-schema.md for the file naming, the exact YAML schema (use it verbatim — do not add, remove, or rename fields), and the field-by-field mapping back to prior phases. Create the docs/decisions/ directory first if it does not exist, then populate every field from the work completed in Phases 1–9.

Update .hitl/current-change.yaml:

  • Add source_artifacts.decision_packet paths for all packets
  • Set status: design-review
  • Set approvals.architecture: pending

After all packets are assembled, update .hitl/current-change.yaml: set status: awaiting-packet-approval. Then post the gate comment and emit the completion output as specified in decision-packet-schema.md.

STOP. Do not set implementation-approved. This session ends here.


Output Summary

Read output-summary.md in this skill's directory and present the completion summary populated with the actual values from this session.

Keep looking

Skills are one crate of 609,856. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.