stack-awareness

name	stack-awareness
description	Ensures tech-stack-aware behavior during workflows. Auto-activates when stack profile rules exist in .claude/rules/stack-*.md. Activates during /arch:init, /context:load, /context:refresh, /deliver, /discern, /diagnose, and /handoff.
allowed-tools	Read, Glob, Grep

Stack Awareness

Tech stack knowledge lives in Stack Profiles — language-specific quality rules generated by /arch:init:

     SPEC (WHAT)          BRAND (HOW IT LOOKS)
    /           \        /
   /             \      /
ADR (HOW+WHY) -- C4 (CONTEXT MAP) -- STACK (HOW TO CODE)

• Specs describe WHAT the system does
• ADRs describe HOW the system is built and WHY
• Brand Guides describe HOW IT LOOKS
• Stack Profiles describe HOW TO CODE — language idioms, verification, anti-patterns

Stack profiles are persistent, project-scoped artifacts generated once and loaded every session.

Stack Profile Organization

Generated Files

.claude/rules/stack-{language}.md    # Language-specific rules (loaded every session)
CLAUDE.md ## Tech Stack              # Compact reference (highest-impact lever)
.claude/settings.json                # Verification command permissions

Source Templates

stacks/                              # Shipped with genie-team
  typescript.md                      # TypeScript profile template
  go.md                              # Go profile template
  rust.md                            # Rust profile template
  csharp.md                          # C# / .NET profile template
  java.md                            # Java profile template
  elixir.md                          # Elixir profile template

When Active

This skill activates during:

• /arch:init — Detect tech stack and generate project-specific configuration
• /context:load — Report active stack profiles and verification status
• /context:refresh — Detect stack profile staleness
• /deliver — Inject stack rules and verification reminders into crafter context
• /discern — Add Stack Compliance to critic review checklist
• /diagnose — Check for stack profile staleness, missing verification tools
• /handoff — Include stack context in transition notes

Behaviors

Common: Stack Profile Loading Pattern

All commands that reference stack profiles follow this pattern:

1. Scan .claude/rules/stack-*.md for active stack profiles
2. If found: Extract language and version from the ## Version: line
3. If multiple stacks: Report all (multi-language projects are common)
4. If no stack profiles found: Silently continue (no warning, no overhead)
5. Never block — stack awareness is valuable but optional

Key principle: Stack is opt-in, like brand-awareness. Not every project needs language-specific rules (e.g., genie-team itself is a prompt engineering project with no application code).

Greenfield projects: When no code exists yet, stack configuration can be set two ways:

1. Directly: /arch:init --stack elixir (team knows the stack)
2. Via workshop: /arch --workshop Phase 2 surfaces "Which tech stack?" when no indicators or profiles exist, then routes to /arch:init --stack {lang}

During /arch:init (Primary — generation)

Detects tech stack and generates configuration after C4 diagrams:

1. If --stack [language] flag is provided: Use the specified stack(s) — skip indicator scanning. Validate against available templates in stacks/. If no version source exists (greenfield), prompt user for version.
2. If no --stack flag: Scan project root for stack indicator files:
   • tsconfig.json → TypeScript
   • go.mod → Go
   • Cargo.toml → Rust
   • *.csproj / *.sln → C# / .NET
   • pom.xml / build.gradle → Java
   • mix.exs → Elixir
3. For each detected/specified stack, read the corresponding template from stacks/{language}.md
4. Generate .claude/rules/stack-{language}.md with version substituted
5. Append compact summary to CLAUDE.md ## Tech Stack section
6. Merge verification permissions into .claude/settings.json
7. Present detection summary to user for confirmation
8. If no --stack flag AND no stack indicators found: prompt user with available stacks from stacks/*.md via AskUserQuestion (skip option available)

Reads: Stack indicator files, stacks/*.md templates Writes: .claude/rules/stack-{language}.md, CLAUDE.md, .claude/settings.json

During /context:load

Reports active stack profiles:

1. Scan .claude/rules/stack-*.md
2. If found: Report for each:

   **Stack:** {Language} {Version}
     - Rules: .claude/rules/stack-{language}.md
     - Verification: {command from rules file}
   

3. If verification tool is not installed: Warn:

   Stack verification command {cmd} not found. Install it for auto-verification.

4. If not found: Silently continue (no "No stack profile" message)

Reads: .claude/rules/stack-*.md Writes: Nothing (read-only)

During /context:refresh

Detects stack profile staleness:

1. Load stack profiles via common pattern
2. If stack profiles exist: a. Check if the version in the profile matches the version in project files b. If version drifted (e.g., go.mod says 1.23 but profile says 1.22):

   Stack profile for Go may be stale — project uses Go 1.23, profile configured for 1.22. Run /arch:init --force to regenerate stack configuration. c. Check if new stack indicators appeared (e.g., a Cargo.toml was added): New stack detected: Rust. Run /arch:init to generate stack configuration.

3. If no stack profiles: Silently continue

Reads: .claude/rules/stack-*.md, stack indicator files Writes: Nothing (drift is reported, user fixes it)

During /deliver

Injects stack rules and verification reminders into crafter context:

1. Load stack profiles via common pattern
2. If stack profiles found: Surface for crafter:

   ## Stack Context
   - Language: {Language} {Version}
   - Verify after changes: `{verification command}`
   - Key rules: {top 3 rules from profile}
   - Anti-patterns to avoid: {top 3 anti-patterns from profile}
   

3. If not found: Silently continue

Reads: .claude/rules/stack-*.md Writes: Nothing (read-only — context injection only)

During /discern

Adds Stack Compliance to critic review:

1. Load stack profiles via common pattern
2. If stack profiles found: Add Stack Compliance section to review checklist:
   • Do error handling patterns follow language idiom?
   • Are modern language features used (version-appropriate)?
   • Are known anti-patterns avoided?
   • Was verification command run after changes?
3. Output Stack Compliance table:

   | Rule | Status | Notes |
   |------|--------|-------|
   | Error wrapping | PASS | All errors wrapped with fmt.Errorf context |
   | Modern idioms | WARN | Manual loop at line 42 could use slices.Contains |
   | Verification | PASS | go vet passed |
   

4. If not found: Silently continue (no Stack Compliance section)

Reads: .claude/rules/stack-*.md, implementation files Writes: Nothing (compliance output goes in review document)

During /diagnose

Checks for stack profile health:

1. Load stack profiles via common pattern
2. If stack profiles found: a. Check version staleness (same as /context:refresh) b. Check if verification tools are installed c. Check if hook verification is configured d. Report stack health:

   ## Stack Health
   - Go 1.22: rules current, go vet available, hook active
   - TypeScript 5.4: rules current, tsc available, hook active
   

3. If not found: Report:

   No stack profiles configured. Run /arch:init to detect and configure tech stack.

Reads: .claude/rules/stack-*.md, stack indicator files, .claude/settings.json Writes: Nothing (diagnostic output only)

During /handoff

Includes stack context in transition notes:

1. Load stack profiles via common pattern
2. If stack profiles found: a. For design → deliver handoff:

   Stack context for Crafter: {Language} {Version} configured. Rules at .claude/rules/stack-{language}.md. Verify with {verification command} after changes. b. For deliver → discern handoff: Stack context for Critic: Review against .claude/rules/stack-{language}.md. Check Stack Compliance section.

3. If not found: Silently continue

Reads: .claude/rules/stack-*.md Writes: Nothing (read-only — guidance injection only)

Stack Update Rules (All Commands)

1. Silently skip, never block — Missing stack profiles are silent. Stack is opt-in.
2. Rules are persistent — .claude/rules/stack-*.md persists across sessions (auto-loaded by Claude Code)
3. Version matters — Rules are version-gated. Go 1.18 rules differ from Go 1.22 rules.
4. Verification is advisory — Hook output helps Claude self-correct but never blocks tool execution
5. Multi-stack is normal — Projects can have TypeScript + Go (e.g., frontend + backend)
6. Regeneration is explicit — /arch:init --force to update; profiles don't auto-update

What This Skill Does NOT Do

• Does NOT block any workflow — silently continues when no stack profiles exist
• Does NOT warn when stack profiles are missing — stack is opt-in
• Does NOT auto-regenerate profiles on version changes — explicit via /arch:init --force
• Does NOT install verification tools — only reports when they're missing
• Does NOT modify source code — only generates Claude Code configuration
• Does NOT replace language-specific linters — complements them with Claude-side guidance