foomakers/assess-stack

/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. [email protected], node@20, [email protected]). Format: name@version. | | $mode | No | Lifecycle mode: bootstrap, implementation, review. Auto-detected if omitted. |

Composed Skills

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

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: /assess-testing owns Testing section, /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 /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 /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

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 /review → review
     • Otherwise → confirm existing adoption (Path B of cascade)
4. Verify: Mode is set.

Step 1: Resolution Cascade

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

1. Check: Is $choice provided?

2. Skip: If not provided, go to Path B.

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

4. Act (bootstrap mode with choice): Confirm the choice and proceed to Step 3.

5. Verify: Choice validated. Proceed to Step 3.

Path B — Adoption Exists

1. Check: Does adoption/tech/tech-stack.md exist with populated core sections?

2. Skip: If not populated or missing, go to Path C.

3. Act: Read current adoption. Present summary:

   Tech stack already adopted. Core sections populated. [Summary of key technologies with versions]

4. Check: Does a corresponding decision record exist?

5. Act: If decision record missing, compose /record-decision to backfill.

6. Verify: Adoption and decision record consistent. Done — exit skill.

Path C — Full Assessment (bootstrap mode)

1. Act: 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: Guidelines and context loaded.

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 — add to tech stack with version + record decision
   2. Reject — flag for removal from implementation

2. Act: If approved → treat as implementation mode addition.

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

4. Verify: Developer decision captured.

Step 4: Write Adoption File

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

Step 5: Record Decision

1. Act: Compose /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"
2. 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 /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) | /assess-stack | Read-only for others | | Monorepo, bundling, release | /assess-stack | Read-only for others | | Linting, formatting, hooks | /assess-stack | Read-only for others | | CLI tooling, markdown/docs | /assess-stack | Read-only for others | | Testing | /assess-testing| /assess-stack reads, never writes | | AI | /assess-ai | /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 /bootstrap:

• Input: /bootstrap invokes /assess-stack during Phase 2 with $mode: bootstrap. May pass $choice for pre-selected stack.
• Output: Returns decision summary and adoption file path.
• /bootstrap includes adoption and ADL changes in the next commit.

When composed by /implement:

• Input: /implement detects new import/dependency → invokes /assess-stack with $choice: [name@version], $mode: implementation.
• Output: Returns validation result (approved/rejected) and adoption file path.
• If rejected (incompatible) → /implement HALTs.

When composed by /review:

• Input: /review detects unlisted dependency → invokes /assess-stack with $choice: [name@version], $mode: review.
• Output: Returns developer decision (approve/reject).
• If rejected → /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 /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 /assess-stack in bootstrap mode first."

Notes

• Lifecycle-spanning: unlike other assess-* skills (primarily bootstrap), /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 /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.