pair-capability-assess-stack

name	pair-capability-assess-stack
description	Evaluates and recommends the tech stack — languages, frameworks, database, libraries, versions — when the choice is open: full evaluation at bootstrap, a single new dependency during implementation ('should we add Redis', 'is this new dependency consistent with our stack'), or composed by /pair-process-review when it finds an unlisted dependency in code. Doesn't audit code already written (that's /pair-capability-verify-adoption). Output-only: emits a proposal + target for /pair-capability-record-decision to persist.
version	0.5.0
author	Foomakers

/pair-capability-assess-stack — Tech Stack Assessment

Evaluate and recommend the technology stack: languages, frameworks, runtime, database, and libraries — all with version tracking. Follows the resolution cascade and operates across the entire project lifecycle. Output-only: produces a proposal (rendered tech-stack.md content + target) plus a report — writes no files. Persistence is delegated to /pair-capability-record-decision.

Arguments

Argument	Required	Description
$choice	No	Technology to assess (e.g. zod@3.22, node@20, react@18.2). Format: name@version.
$mode	No	Lifecycle mode: bootstrap, implementation, review. Auto-detected if omitted.

Composed Skills

Output-only — composes no skill, writes no files; the caller persists via /pair-capability-record-decision (see Composition Interface).

Proposal Target

The rendered adoption content is destined for this file — the caller writes it via /pair-capability-record-decision:

• Target: adoption/tech/tech-stack.md — core sections only
• Ownership: Core sections only — see Section Ownership below for the full table (Testing owned by /pair-capability-assess-testing, AI by /pair-capability-assess-ai).

Lifecycle Modes

Bootstrap Mode

Full stack evaluation. Used when no tech stack is defined yet. Evaluates language, framework, runtime, database, key libraries. Renders the initial tech-stack.md proposal with all core sections and versions for the caller to persist.

Implementation Mode

Add or update a single dependency. Used when /pair-process-implement detects a new dependency or developer wants to add a library. Validates compatibility with existing stack and renders the affected-entry proposal; the caller (e.g. /pair-process-implement) persists it via /pair-capability-record-decision.

Review Mode

Detect and evaluate unlisted dependencies. Used when /pair-process-review finds a dependency in code that isn't in tech-stack.md. Presents approve/reject options to developer. If approved, renders the entry proposal for the caller to persist.

Algorithm

Step 0: Detect Lifecycle Mode

1. Check: Is $mode provided?
2. Skip: If provided, use it. Proceed to Step 1.
3. Act: Auto-detect mode:
   • $choice provided AND tech-stack.md has populated core sections → implementation (adding to existing stack)
   • $choice provided AND tech-stack.md missing or empty → bootstrap (initial setup with override)
   • No $choice AND tech-stack.md missing or empty → bootstrap (full assessment)
   • No $choice AND tech-stack.md populated → check caller context
     • Called by /pair-process-review → review
     • Otherwise → confirm existing adoption (Path B of cascade)
4. Verify: Mode is set.

Step 1: Resolution Cascade

Read resolution cascade for the generic Path A/B/C mechanics (check → skip → act → verify).

• Path A delta (implementation or bootstrap with $choice): parse $choice as name@version; in implementation mode, validate against tech-stack.md for version incompatibility, duplicate entry, or category conflict — warn and offer resolve-or-reject if found. In bootstrap mode with a choice, just confirm. Proceed to Step 3.
• Path B delta: adoption check is adoption/tech/tech-stack.md with populated core sections. If a corresponding decision record is missing, report the gap (this skill still writes nothing; the caller persists a backfill via /pair-capability-record-decision).
• Path C delta (bootstrap mode): proceed to Step 2 (full assessment).

Step 2: Read Guidelines (bootstrap mode only)

1. Act: Read technology guidelines:
   • Technology Stack Standards — stack requirements
   • Framework Selection — evaluation criteria
   • Tech Decisions — decision frameworks
   • Conventions — naming and coding conventions
2. Act: Read project context:
   • adoption/product/PRD.md — project type, scale, constraints
   • adoption/tech/architecture.md — architecture pattern (stack must support it)
3. Verify: Every file listed in 1-2 above has been read; any that's missing follows Graceful Degradation (ask the developer directly) instead of silently proceeding to Step 3.

Step 3: Evaluate and Decide

Bootstrap Mode (full evaluation)

1. Act: For each core category, evaluate options:

   • Language: Primary development language
   • Framework: Web/CLI/application framework
   • Runtime: Execution environment with version
   • Database: If applicable, persistence layer
   • Package manager: Dependency management
   • Monorepo tooling: If applicable
   • Core libraries: Essential libraries (CLI parsing, formatting, etc.)
   • Bundling: Build and packaging tools
   • Linting/formatting: Code quality tools with versions
   • Release management: Versioning and changelog tools

2. Act: For each category, use guideline evaluation criteria:

   • Compatibility with chosen language and architecture
   • Community health and maintenance status
   • Team familiarity and learning curve
   • License compatibility

3. Act: Present full stack recommendation with versions:

   Tech Stack Recommendation:

Category	Technology	Version	Rationale
Language	[name]	[vX.Y]	[reason]
...	...	...	...

1. Verify: Developer approves the full stack.

Implementation Mode (add single entry)

1. Act: Confirm the addition:

   Adding to tech stack: $choice

   • Category: [auto-detected or ask]
   • Compatible: [yes/no — details]
   • Rationale: [developer provides or auto-inferred]

2. Verify: Developer approves.

Review Mode (unlisted dependency detected)

1. Act: Present finding to developer:

   Unlisted dependency detected: [name@version] Found in: [file(s)] Not listed in tech-stack.md.

   Options:

   1. Approve — render entry proposal for the caller to add to stack + record decision
   2. Reject — flag for removal from implementation

2. Act: If approved → treat as implementation mode addition (render entry proposal).

3. Act: If rejected → report back to caller (e.g. /pair-process-review marks as CHANGES-REQUESTED).

4. Verify: Developer decision captured.

Step 4: Render Adoption Proposal

1. Act (bootstrap mode): Render full tech-stack.md content with all core sections. Include version for every entry.
2. Act (implementation/review mode): Render the affected-entry content for the appropriate section, scoped so the caller's write preserves all other content, including sections owned by /pair-capability-assess-testing and /pair-capability-assess-ai.
3. Verify: The rendered content and its target are ready to emit. All entries have versions; section ownership respected.

Step 5: Emit Proposal

1. Act: Emit the proposal to the caller:
   • content: the rendered tech-stack.md body (full or affected entry) from Step 4
   • target: adoption/tech/tech-stack.md (core sections)
   • decision-metadata (by mode):
     • Bootstrap: $type: non-architectural, $topic: tech-stack-initial, $summary: "Initial tech stack adopted: [key technologies]"
     • Implementation: $type: non-architectural, $topic: stack-add-[name], $summary: "[name]@[version] added to tech stack — [rationale]"
     • Review approve: $type: non-architectural, $topic: stack-approve-[name], $summary: "[name]@[version] approved during review — added to tech stack"
   • plus the human-facing report (see Output Format), and the validation result (approved/rejected) for implementation/review modes
2. Verify: Proposal emitted — see record-decision invocation contract for the persistence contract (persistence is always the caller's responsibility, delegated to /pair-capability-record-decision).

Version Tracking Policy

• Every entry in tech-stack.md MUST include a version: [tool] v[X.Y.Z] or [tool]@[X.Y.Z].
• Major.minor required, patch optional.
• Version updates go through /pair-capability-assess-stack: check compatibility with existing stack, render the updated entry proposal; the caller persists via /pair-capability-record-decision.
• Version format in adoption file: human-readable prose (e.g. "vitest v3.2.4 is adopted").

Section Ownership

Section	Owner	Other Skills
Core (language, framework, runtime, DB)	/pair-capability-assess-stack	Read-only for others
Monorepo, bundling, release	/pair-capability-assess-stack	Read-only for others
Linting, formatting, hooks	/pair-capability-assess-stack	Read-only for others
CLI tooling, markdown/docs	/pair-capability-assess-stack	Read-only for others
Testing	/pair-capability-assess-testing	/pair-capability-assess-stack only reads it
AI	/pair-capability-assess-ai	/pair-capability-assess-stack only reads it

Output Format

Follows the Decision Shape (with an added Mode line — a legitimate per-skill variant, see that file, since this skill spans the whole project lifecycle).

ASSESSMENT COMPLETE (output-only — no files written):
├── Domain:    Tech Stack
├── Mode:      [Bootstrap | Implementation | Review]
├── Path:      [Argument Override | Adoption Exists | Full Assessment]
├── Decision:  [technology@version — or full stack summary]
├── Proposal:  [content rendered for tech-stack.md — full | affected entry]
├── Target:    adoption/tech/tech-stack.md (core sections)
├── Persist:   [caller composes /record-decision(content, target) → ADL]
└── Status:    [Proposal ready | Confirmed existing | Approved | Rejected]

Composition Interface

See record-decision invocation contract for the generic tuple + Input/Output/Persistence shape.

When composed by /pair-process-bootstrap:

• Input: /pair-process-bootstrap invokes /pair-capability-assess-stack during Phase 2 with $mode: bootstrap. May pass $choice for pre-selected stack.
• Persistence: /pair-process-bootstrap composes /pair-capability-record-decision, then includes those changes in the next commit.

When composed by /pair-process-implement:

• Input: /pair-process-implement detects new import/dependency → invokes /pair-capability-assess-stack with $choice: [name@version], $mode: implementation.
• Output: Returns the validation result (approved/rejected) plus, when approved, the proposal.
• Persistence: on approval, /pair-process-implement persists the entry via /pair-capability-record-decision. If rejected (incompatible) → /pair-process-implement HALTs.

When composed by /pair-process-review:

• Input: /pair-process-review detects unlisted dependency → invokes /pair-capability-assess-stack with $choice: [name@version], $mode: review.
• Output: Returns the developer decision (approve/reject) plus, when approved, the proposal.
• Persistence: on approval, /pair-process-review persists via /pair-capability-record-decision. If rejected → /pair-process-review includes as CHANGES-REQUESTED finding.

When invoked independently: mode auto-detected. The skill returns the proposal; the human (or agent) persists it by composing /pair-capability-record-decision, then commits.

Edge Cases

• Argument conflicts with adoption: Warn developer with details, ask for confirmation.
• Version conflict: Library requires runtime version different from adopted → warn, propose resolution (upgrade runtime or reject library).
• Duplicate entry: Same library already in stack → check if version differs. If same, skip. If different, treat as version update.
• Multiple skills rendering same file: Section ownership prevents conflicts. Each skill renders only its sections; the caller's write preserves the rest.
• tech-stack.md exists but missing core sections: Render content that fills gaps; the caller's write preserves existing content.
• Decision record already exists for same scope+decision: Report "already recorded" — no proposal to persist (no duplicates).

Graceful Degradation

See graceful degradation (guideline missing → ask developer for stack choices directly; adoption file missing in bootstrap mode → the skill still runs, caller creates it on persist) and record-decision contract (persistence unavailable → proposal stands as a report) for the standard scenarios. Additional cases:

• If architecture.md doesn't exist, warn: "No architecture adopted — stack compatibility cannot be verified against architecture."
• If tech-stack.md doesn't exist in implementation/review mode (as opposed to bootstrap, covered above), HALT: "No tech stack defined — run /pair-capability-assess-stack in bootstrap mode first."

Notes

• Tech stack as registry: tech-stack.md is the registry of approved technologies. Only listed technologies are approved. Unlisted technologies detected during review trigger /pair-capability-assess-stack evaluation.
• Stack decisions are typically non-architectural → the caller records them as an ADL. Exception: if a stack choice fundamentally changes the architecture (e.g. switching from monolith to microservices runtime), the caller uses ADR.
• Educational content (technology descriptions, ecosystem overview, WHY) stays in guidelines. This skill references guidelines for evaluation criteria and comparison matrices.