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

Evaluate and decide on the technology stack: languages, frameworks, runtime, database, and libraries — all with version tracking. Follows the resolution cascade and operates across the entire project lifecycle.

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

Skill	Type	Required
`/pair-capability-record-decision`	Capability	Yes — records stack decision as ADL (or ADR)

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).

Adoption File

Target: adoption/tech/tech-stack.md — core sections only
Ownership: Core sections (language, framework, runtime, database, monorepo, bundling, release, linting, git hooks, CLI tooling, markdown/docs)
Shared file: /pair-capability-assess-testing owns Testing section, /pair-capability-assess-ai owns AI section

Lifecycle Modes

Bootstrap Mode

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

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, adds to tech-stack.md with version, records 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, adds to stack and records decision.

Algorithm

Step 0: Detect Lifecycle Mode

Check: Is $mode provided?
Skip: If provided, use it. Proceed to Step 1.
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)
Verify: Mode is set.

Step 1: Resolution Cascade

Path A — Argument Override (implementation or bootstrap with $choice)

Check: Is $choice provided?
Skip: If not provided, go to Path B.
Act (implementation mode): Validate compatibility:
- Parse $choice as name@version.
- Check existing tech-stack.md for conflicts:
  - Version incompatibility (e.g. library needs Node 20, stack has Node 18)
  - Duplicate entry (same library already listed)
  - Category conflict (e.g. two ORMs)
- If conflict detected, warn developer:
  Compatibility issue: $choice conflicts with existing stack.
  - Conflict: [description]
  - Options: (a) resolve conflict and proceed, (b) reject addition
Act (bootstrap mode with choice): Confirm the choice and proceed to Step 3.
Verify: Choice validated. Proceed to Step 3.

Path B — Adoption Exists

Check: Does adoption/tech/tech-stack.md exist with populated core sections?
Skip: If not populated or missing, go to Path C.
Act: Read current adoption. Present summary:

Tech stack already adopted. Core sections populated. [Summary of key technologies with versions]
Check: Does a corresponding decision record exist?
Act: If decision record missing, compose /pair-capability-record-decision to backfill.
Verify: Adoption and decision record consistent. Done — exit skill.

Path C — Full Assessment (bootstrap mode)

Act: Proceed to Step 2 (full assessment).

Step 2: Read Guidelines (bootstrap mode only)

Act: Read technology guidelines:
- Technology Stack Standards — stack requirements
- Framework Selection — evaluation criteria
- Tech Decisions — decision frameworks
- Conventions — naming and coding conventions
Act: Read project context:
- adoption/product/PRD.md — project type, scale, constraints
- adoption/tech/architecture.md — architecture pattern (stack must support it)
Verify: Guidelines and context loaded.

Step 3: Evaluate and Decide

Bootstrap Mode (full evaluation)

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
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
Act: Present full stack recommendation with versions:

Tech Stack Recommendation:

Category Technology Version Rationale

Language [name] [vX.Y] [reason]

... ... ... ...

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

Verify: Developer approves the full stack.

Implementation Mode (add single entry)

Act: Confirm the addition:
Adding to tech stack: $choice
- Category: [auto-detected or ask]
- Compatible: [yes/no — details]
- Rationale: [developer provides or auto-inferred]
Verify: Developer approves.

Review Mode (unlisted dependency detected)

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

Options:
1. Approve — add to tech stack with version + record decision
2. Reject — flag for removal from implementation
Act: If approved → treat as implementation mode addition.
Act: If rejected → report back to caller (e.g. /pair-process-review marks as CHANGES-REQUESTED).
Verify: Developer decision captured.

Step 4: Write Adoption File

Check: Does adoption/tech/tech-stack.md exist?
Act (bootstrap mode): Write full tech-stack.md with all core sections. Include version for every entry.
Act (implementation/review mode): Add or update only the affected entry in the appropriate section. Preserve all other content, including sections owned by /pair-capability-assess-testing and /pair-capability-assess-ai.
Verify: Adoption file written. All entries have versions. Section ownership respected.

Step 5: Record Decision

Act: Compose /pair-capability-record-decision:
- 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"
Verify: Decision record created. Adoption file consistent with record.

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, update adoption, write decision record.
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 reads, never writes
AI	`/pair-capability-assess-ai`	/pair-capability-assess-stack reads, never writes

Output Format

ASSESSMENT COMPLETE:
├── Domain:    Tech Stack
├── Mode:      [Bootstrap | Implementation | Review]
├── Path:      [Argument Override | Adoption Exists | Full Assessment]
├── Decision:  [technology@version — or full stack summary]
├── Adoption:  [tech-stack.md — written | confirmed | updated | entry added]
├── Record:    [ADL path — created | exists | backfilled]
└── Status:    [Complete | Confirmed existing | Approved | Rejected]

Composition Interface

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.
Output: Returns decision summary and adoption file path.
/pair-process-bootstrap includes adoption and ADL 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 validation result (approved/rejected) and adoption file path.
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 developer decision (approve/reject).
If rejected → /pair-process-review includes as CHANGES-REQUESTED finding.

When invoked independently:

Full interactive flow. Mode auto-detected. Developer commits changes.

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 writing same file: Section ownership prevents conflicts. Each skill writes only its sections.
tech-stack.md exists but missing core sections: Fill gaps, preserve existing content.
Decision record already exists for same scope+decision: Skip writing (no duplicates).

Graceful Degradation

If technology guidelines are not found, use minimal assessment: ask developer for stack choices directly.
If /pair-capability-record-decision is not installed, warn and skip decision recording.
If architecture.md doesn't exist, warn: "No architecture adopted — stack compatibility cannot be verified against architecture."
If tech-stack.md doesn't exist (bootstrap mode), create it. If implementation/review mode, HALT: "No tech stack defined — run /pair-capability-assess-stack in bootstrap mode first."

Notes

Lifecycle-spanning: unlike other assess-* skills (primarily bootstrap), /pair-capability-assess-stack is used throughout bootstrap, implementation, and review.
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 → produce ADL. Exception: if a stack choice fundamentally changes the architecture (e.g. switching from monolith to microservices runtime), use ADR.
Section ownership prevents parallel write conflicts: each assess-* skill owns its sections, preserves others.
Educational content (technology descriptions, ecosystem overview, WHY) stays in guidelines. This skill references guidelines for evaluation criteria and comparison matrices.

pair-capability-assess-stack

SKILL.md.claude/skills/pair-capability-assess-stack/SKILL.md