# yingsun1004/stackshift architecture

> Architecture diagram of the GitHub repository yingsun1004/stackshift, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yingsun1004/stackshift
- Repository: https://github.com/yingsun1004/stackshift

## Overview

StackShift is an instruction-only learning Skill for experienced engineers changing technology stacks. A learner’s goal and existing experience shape a transfer map, gap/risk analysis, and feasibility-checked learning path; the selected mode then guides Learn → Apply → Verify and evidence-based readiness. The shared behavior is packaged for Codex and Claude Code, though the README says evaluation depth differs. The README documents the capabilities and stages below; sampled source was limited to evaluation/requalification helpers, not the Skill implementation itself.

Main entry points: [`.agents/skills/stackshift`](https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift) (Learn Apply Verify), [`.claude/skills/stackshift`](https://github.com/yingsun1004/stackshift/tree/main/.claude/skills/stackshift) (Claude package), [`.agents/skills/stackshift/SKILL.md`](https://github.com/yingsun1004/stackshift/blob/main/.agents/skills/stackshift/SKILL.md) (Behavior contract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_packages["Runtime packages"]
  node_codex_skill["Codex package<br/>[stackshift]"]
  node_claude_skill["Claude package<br/>[stackshift]"]
  node_contract["Behavior contract<br/>[SKILL.md]"]
end

subgraph group_planning["Transfer planning"]
  node_experience["Prior experience<br/>[stackshift]"]
  node_transfer["Transfer map<br/>[stackshift]"]
  node_gaps["Gap and risk map<br/>[stackshift]"]
  node_feasibility["Goal feasibility<br/>[stackshift]"]
  node_path["Learning path<br/>[stackshift]"]
end

subgraph group_learning["Learning and evidence"]
  node_modes["Learning modes<br/>[stackshift]"]
  node_repo_map["Repository mapping<br/>[stackshift]"]
  node_loops["Learn Apply Verify<br/>[stackshift]"]
  node_evidence["Readiness evidence<br/>[stackshift]"]
  node_persistence["Journey persistence<br/>[stackshift]"]
end

node_learner(("Learner"))
node_codex(("Codex"))
node_claude(("Claude Code"))

node_codex -->|"invokes"| node_codex_skill
node_claude -->|"invokes"| node_claude_skill
node_codex_skill -->|"packages"| node_contract
node_claude_skill -->|"shares behavior"| node_contract
node_learner -->|"provides"| node_experience
node_learner -->|"states goal"| node_feasibility
node_experience -->|"classifies"| node_transfer
node_transfer -->|"identifies deltas"| node_gaps
node_gaps -->|"informs"| node_feasibility
node_feasibility -->|"bounds"| node_path
node_path -->|"shapes"| node_modes
node_modes -->|"selects"| node_loops
node_learner -->|"requests repo help"| node_repo_map
node_repo_map -->|"grounds learning"| node_loops
node_loops -->|"produces observations"| node_evidence
node_learner -->|"demonstrates work"| node_evidence
node_evidence -->|"guides next action"| node_loops
node_learner -->|"consents"| node_persistence
node_persistence -->|"resumes checkpoint"| node_loops

click node_codex_skill "https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift"
click node_claude_skill "https://github.com/yingsun1004/stackshift/tree/main/.claude/skills/stackshift"
click node_contract "https://github.com/yingsun1004/stackshift/blob/main/.agents/skills/stackshift/SKILL.md"
click node_experience "https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift"
click node_transfer "https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift"
click node_gaps "https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift"
click node_feasibility "https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift"
click node_path "https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift"
click node_modes "https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift"
click node_repo_map "https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift"
click node_loops "https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift"
click node_evidence "https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift"
click node_persistence "https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_codex_skill,node_claude_skill,node_contract toneBlue
class node_experience,node_transfer,node_gaps,node_feasibility,node_path toneAmber
class node_modes,node_repo_map,node_loops,node_evidence,node_persistence toneMint
class node_learner,node_codex,node_claude toneIndigo
```

## Components

### Runtime packages

- [Codex package](https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift): `.agents/skills/stackshift`
- [Claude package](https://github.com/yingsun1004/stackshift/tree/main/.claude/skills/stackshift): `.claude/skills/stackshift`
- [Behavior contract](https://github.com/yingsun1004/stackshift/blob/main/.agents/skills/stackshift/SKILL.md): `.agents/skills/stackshift/SKILL.md`

### Transfer planning

- [Prior experience](https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift): `.agents/skills/stackshift`
- [Transfer map](https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift): `.agents/skills/stackshift`
- [Gap and risk map](https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift): `.agents/skills/stackshift`
- [Goal feasibility](https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift): `.agents/skills/stackshift`
- [Learning path](https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift): `.agents/skills/stackshift`

### Learning and evidence

- [Learning modes](https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift): `.agents/skills/stackshift`
- [Repository mapping](https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift): `.agents/skills/stackshift`
- [Learn Apply Verify](https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift): `.agents/skills/stackshift`
- [Readiness evidence](https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift): `.agents/skills/stackshift`
- [Journey persistence](https://github.com/yingsun1004/stackshift/tree/main/.agents/skills/stackshift): `.agents/skills/stackshift`

### Other components

- **Learner**
- **Codex**
- **Claude Code**

## Connections

- Codex → Codex package: invokes
- Claude Code → Claude package: invokes
- Codex package → Behavior contract: packages
- Claude package → Behavior contract: shares behavior
- Learner → Prior experience: provides
- Learner → Goal feasibility: states goal
- Prior experience → Transfer map: classifies
- Transfer map → Gap and risk map: identifies deltas
- Gap and risk map → Goal feasibility: informs
- Goal feasibility → Learning path: bounds
- Learning path → Learning modes: shapes
- Learning modes → Learn Apply Verify: selects
- Learner → Repository mapping: requests repo help
- Repository mapping → Learn Apply Verify: grounds learning
- Learn Apply Verify → Readiness evidence: produces observations
- Learner → Readiness evidence: demonstrates work
- Readiness evidence → Learn Apply Verify: guides next action
- Learner → Journey persistence: consents
- Journey persistence → Learn Apply Verify: resumes checkpoint