@a-company/paradigm 5.38.0 → 6.0.2

package/dist/university-content/courses/para-001.json

@@ -1,166 +0,0 @@
-{
-  "id": "para-001",
-  "title": "PARA 001: Quick Start",
-  "description": "Get productive with Paradigm in 15 minutes. Initialize a project, meet your agent team, and build your first feature with orchestration. Hands-on from the first minute — theory comes later.",
-  "lessons": [
-    {
-      "id": "shift-setup",
-      "title": "Your First paradigm shift",
-      "content": "## Hands On in 60 Seconds\n\nOpen a terminal in any project directory and run:\n\n```bash\nparadigm shift\n```\n\nThat is it. One command, and your project is Paradigm-aware.\n\n### What Just Happened?\n\nLook at your directory. Several new files and a new folder appeared:\n\n```\n.paradigm/            ← Configuration, roster, tags, indexes\n  config.yaml         ← Project settings (name, discipline, enforcement)\n  roster.yaml         ← Your agent team\n  agents.yaml         ← Model tier assignments\n  tags.yaml           ← Tag taxonomy\nCLAUDE.md             ← Instructions for Claude Code\nAGENTS.md             ← Instructions for any AI agent\n.purpose              ← Root-level purpose file (describes your project)\n```\n\nEach file has a specific job:\n\n- **`.paradigm/config.yaml`** is the brain — it stores your project name, discipline (web, backend, mobile, etc.), enforcement level, and feature flags. Paradigm auto-detected your discipline from project markers like `package.json`, `Cargo.toml`, or `go.mod`.\n\n- **`CLAUDE.md`** and **`AGENTS.md`** are instruction files that AI tools read automatically. They are generated from your Paradigm configuration — you do not edit them by hand. When you change config, re-running `paradigm shift` regenerates them.\n\n- **`.purpose`** is the most important file type in Paradigm. It describes what code in a directory does using a structured format with **symbols** — you will learn all five symbol types in PARA 101. For now, just know that `.purpose` files are how AI agents understand your codebase.\n\n- **`roster.yaml`** lists which agents are on your team. More on this in the next lesson.\n\n### Hooks Are Installed\n\n`paradigm shift` also installed Git hooks and Claude Code hooks. These run automatically when you commit or finish a task, checking that your Paradigm metadata stays in sync with your code.\n\nBy default, hooks use **minimal enforcement** — they warn but never block. You will not lose work or get stuck. As you get comfortable, you can upgrade to balanced or strict enforcement (covered in PARA 301).\n\n### Try It: Explore What Was Created\n\nRun these commands to see what Paradigm set up:\n\n```bash\ncat .paradigm/config.yaml      # Your project configuration\ncat .paradigm/roster.yaml       # Your agent team\ncat .purpose                    # Root purpose file\n```\n\nNotice how `config.yaml` already knows your project type, and `roster.yaml` has agents selected for that type. This is the auto-detection at work — no manual configuration needed.",
-      "keyConcepts": [
-        "paradigm shift is the one-command setup — run it in any project directory",
-        ".paradigm/ directory holds configuration, roster, tags, and indexes",
-        "CLAUDE.md and AGENTS.md are auto-generated AI instruction files",
-        ".purpose files describe code directories using structured symbols",
-        "Hooks use minimal enforcement by default — warn but never block"
-      ],
-      "quiz": [
-        {
-          "id": "q1",
-          "question": "You just ran paradigm shift in a Node.js project. Which of the following was NOT created or configured automatically?",
-          "choices": {
-            "A": ".paradigm/config.yaml with discipline auto-detected from package.json",
-            "B": "CLAUDE.md with AI instructions derived from your configuration",
-            "C": "A comprehensive test suite for your existing code",
-            "D": "Git hooks for automated compliance checking",
-            "E": ".paradigm/roster.yaml with agents suited for a Node.js project"
-          },
-          "correct": "C",
-          "explanation": "paradigm shift sets up Paradigm metadata and tooling — it does not generate tests, modify your source code, or create application logic. It creates configuration, instruction files, hooks, and an agent roster. Testing is handled by the Vigil agent during orchestration, not during initialization."
-        },
-        {
-          "id": "q2",
-          "question": "After running paradigm shift, you edit .paradigm/config.yaml to change your enforcement level. Now CLAUDE.md is out of date. How do you update it?",
-          "choices": {
-            "A": "Edit CLAUDE.md manually to match your changes",
-            "B": "Run paradigm shift again — it regenerates CLAUDE.md from your updated config",
-            "C": "Delete CLAUDE.md and it will regenerate on the next commit",
-            "D": "Run paradigm sync to rebuild only the instruction files",
-            "E": "Both B and D would work — shift re-runs all steps including sync, while sync targets just the instruction files"
-          },
-          "correct": "E",
-          "explanation": "CLAUDE.md is a derived file — always generated from config, never hand-edited. Both paradigm shift (full re-run) and paradigm sync (targeted) will regenerate it. Use sync when you only changed config; use shift when you want the full pipeline (migrate, scan, hooks, etc.)."
-        },
-        {
-          "id": "q3",
-          "question": "A teammate says \"I ran paradigm shift but it broke my project — hooks are blocking my commits.\" This should not happen with default settings. What likely went wrong?",
-          "choices": {
-            "A": "paradigm shift always uses strict enforcement",
-            "B": "The project already had a config.yaml with enforcement level set to strict or balanced from a previous setup",
-            "C": "Hooks always block on the first run to teach discipline",
-            "D": "The teammate's Git version is incompatible with Paradigm hooks",
-            "E": "paradigm shift requires admin privileges to install hooks"
-          },
-          "correct": "B",
-          "explanation": "New projects default to minimal enforcement, which warns but never blocks. But paradigm shift is idempotent — if the project already had a .paradigm/config.yaml with a higher enforcement level, shift preserves that setting. The teammate's project was likely previously configured with balanced or strict enforcement. Check config.yaml and adjust enforcement.level if needed."
-        }
-      ]
-    },
-    {
-      "id": "meet-the-team",
-      "title": "Meet Your Agent Team",
-      "content": "## Your AI Team\n\nOpen `.paradigm/roster.yaml`. You will see a list of agents — your project's AI team. Each agent has a specific role, and the orchestrator assigns them to tasks based on what the task needs.\n\n### The 8 Core Agents\n\nEvery project gets these eight. They are the backbone of Paradigm's orchestration:\n\n| Agent | Role | What They Do |\n|-------|------|-------------|\n| **Architect** | Design | Plans multi-file changes, defines structure |\n| **Builder** | Implementation | Writes the code |\n| **Reviewer** | Quality | Two-stage review: spec compliance → code quality |\n| **Sage** | Advocacy | Represents the user's perspective, UX implications |\n| **Jinx** | Advocacy | Stress-tests assumptions, finds edge cases |\n| **Sentinel** | Security | Threat analysis, auth review, vulnerability scanning |\n| **Vigil** | Testing | Writes tests, checks coverage, validates edge cases |\n| **Doc** | Documentation | Maintains .purpose files and portal.yaml |\n| **Rune** | Compliance | Plans symbols before building, validates after |\n\n### Model Tiers\n\nNot every agent needs the most powerful (and expensive) model. Paradigm assigns agents to tiers:\n\n- **Tier 1 (opus)** — Architect, Sentinel. Complex reasoning, design decisions, threat analysis.\n- **Tier 2 (sonnet)** — Reviewer, Sage, Jinx, Doc, Rune. Balanced depth and speed.\n- **Tier 3 (haiku)** — Builder, Vigil. Fast, cost-effective for implementation and testing.\n\nThis is not a quality ranking — it is a complexity match. Building code is well-defined work that a fast model handles efficiently. Designing architecture requires deeper reasoning that benefits from a more capable model.\n\n### Specialized and Ecosystem Agents\n\nBeyond the 8 core agents, Paradigm has **54+ agents** total:\n\n- **Specialized agents** (~20) cover domains like mobile, database, DevOps, accessibility, performance, and internationalization. They are added to your roster when your project type matches.\n\n- **Ecosystem agents** (~26+) are language/platform-specific: Swift, TypeScript, Rust, Python ML, iOS, Android, etc. They accumulate knowledge through notebooks that transfer across projects.\n\nYou do not need to manage these manually. `paradigm shift` detected your project type and selected the right mix. You can view and customize your roster with:\n\n```bash\nparadigm agent list          # See your full roster\nparadigm agent activate <id> # Add an agent\nparadigm agent bench <id>    # Remove an agent\n```\n\n### The Maestro Model\n\nYou are **Maestro** — the orchestrator. When you give a task to Paradigm, you are not talking to one AI. You are conducting a team:\n\n1. **Rune** plans the symbols the task needs\n2. **Architect** designs the approach (for complex tasks)\n3. **Sentinel** reviews security implications (when auth or data is involved)\n4. **Builder** writes the code\n5. **Reviewer** checks spec compliance and code quality\n6. **Doc** updates .purpose files and Paradigm metadata\n7. **Rune** validates the symbols match the implementation\n\nNot every task uses every agent. A simple CSS fix might only need Builder. A new API endpoint might need Architect → Sentinel → Builder → Reviewer → Doc → Rune. The orchestrator decides based on the task.\n\n> **Going deeper:** PARA 401 covers orchestration mechanics (facets, handoffs, trigger patterns). PARA 701 covers the full agent roster, profiles, notebooks, and learning loops.",
-      "keyConcepts": [
-        "8 core agents are in every project: Architect, Builder, Reviewer, Sage, Jinx, Sentinel, Vigil, Doc, Rune",
-        "54+ total agents across three tiers: core, specialized, ecosystem",
-        "Model tiers match agent complexity: opus for design, sonnet for analysis, haiku for execution",
-        "paradigm shift auto-selects agents based on project type",
-        "You are Maestro — the human orchestrator conducting the agent team"
-      ],
-      "quiz": [
-        {
-          "id": "q1",
-          "question": "Your project is a React frontend with no backend. Which of these agents would paradigm shift likely NOT include in your roster?",
-          "choices": {
-            "A": "Builder — every project needs code implementation",
-            "B": "A database specialist — there is no database in a frontend-only project",
-            "C": "Reviewer — code review is universal",
-            "D": "Rune — symbol compliance applies to all projects",
-            "E": "Sentinel — even frontend apps have security concerns (XSS, CSRF)"
-          },
-          "correct": "B",
-          "explanation": "Specialized agents like a database specialist are only rostered when the project type matches. A React frontend with no backend has no database layer, so database agents would not be selected. The 8 core agents (including Sentinel — frontend security matters) appear in every roster. Specialized and ecosystem agents are added based on detection."
-        },
-        {
-          "id": "q2",
-          "question": "The Architect uses opus (tier-1) while the Builder uses haiku (tier-3). A junior developer asks: \"Does that mean the builder writes worse code?\" How do you explain?",
-          "choices": {
-            "A": "Yes — tier-3 is lower quality, but it is faster and cheaper",
-            "B": "No — tiers match complexity, not quality. Architecture requires open-ended reasoning (opus). Building is well-defined implementation work where speed matters more (haiku).",
-            "C": "The tiers are just labels with no real difference",
-            "D": "The builder should be upgraded to opus for important features",
-            "E": "All agents should use the same model for consistency"
-          },
-          "correct": "B",
-          "explanation": "Model tier assignment is about matching the nature of the work, not ranking quality. Architectural design is open-ended — \"how should we structure this?\" benefits from deeper reasoning. Implementation is well-defined — \"write this function that does X\" benefits from speed. A fast model writing clearly specified code often produces better results than an overthinking model."
-        },
-        {
-          "id": "q3",
-          "question": "You want to add a DevOps specialist agent to your web project's roster. What command would you use?",
-          "choices": {
-            "A": "Edit roster.yaml by hand and add the agent definition",
-            "B": "paradigm agent activate devops — it adds the agent to your project roster",
-            "C": "paradigm shift --add-agent devops",
-            "D": "Re-run paradigm shift and hope it detects the need",
-            "E": "DevOps agents cannot be added to web projects"
-          },
-          "correct": "B",
-          "explanation": "paradigm agent activate <id> adds an agent to your project roster. This is the proper way to customize your team — the CLI updates roster.yaml, agents.yaml, and any related configuration atomically. While you could edit roster.yaml by hand, using the CLI ensures all related files stay in sync."
-        }
-      ]
-    },
-    {
-      "id": "build-something",
-      "title": "Build With the Team",
-      "content": "## Your First Orchestrated Task\n\nYou have a project set up and a team rostered. Now let's build something and see the full loop in action.\n\n### The Workflow\n\nEvery task in Paradigm follows this pattern:\n\n```\n1. Quick-check or plan   →  Is this task ready to build?\n2. Orchestrate           →  Assign the right agents\n3. Build                 →  Agents do the work\n4. Review                →  Spec compliance + code quality\n5. Commit                →  With symbol references in the message\n```\n\n### Step 1: Start with a Quick-Check\n\nBefore writing any code, ask the orchestrator if your task is ready:\n\n```\nparadigm_orchestrate_inline({\n  task: \"Add a health check endpoint at GET /health\",\n  mode: \"quick\"\n})\n```\n\nQuick-check runs two agents — **Jinx** stress-tests your assumptions (\"What should /health return? Just 200 OK, or system status?\") and a **reviewer** checks feasibility (\"Single file change, no auth needed\"). You get back either:\n\n- **GREENLIGHT** — go ahead and build\n- **ESCALATE** — needs full planning first\n\nA simple health endpoint would likely get GREENLIGHT.\n\n### Step 2: Build\n\nWith a greenlight, proceed to implementation. If you are using Claude Code with Paradigm, the agent team handles this automatically during orchestration. For a simple task:\n\n- **Builder** writes the endpoint\n- **Rune** ensures the component is documented in `.purpose`\n- **Reviewer** checks that the implementation matches Paradigm metadata\n\n### Step 3: Review the Output\n\nThe reviewer runs two stages:\n\n1. **Spec Compliance** — Is `#health-check` registered in a `.purpose` file? If a gate is needed, is it in `portal.yaml`? (A public health endpoint typically needs no gate.)\n2. **Code Quality** — Is the implementation clean, secure, and tested?\n\nIf Stage 1 fails, the reviewer stops and sends the task back. No point reviewing code quality of undocumented code.\n\n### Step 4: Commit\n\nParadigm uses structured commit messages with symbol references:\n\n```\nfeat(#health-check): add GET /health endpoint\n\n- Add #health-check component returning system status\n- No gate required — public endpoint\n\nSymbols: #health-check\n```\n\nThe `Symbols:` trailer is parsed by the post-commit hook for automatic history capture. This means every change is traceable to the symbols it affected.\n\n### What If You Skip Orchestration?\n\nYou can always write code directly without orchestrating. On minimal enforcement (the default), nothing blocks you. But you lose:\n\n- **Pre-build risk assessment** — Jinx might have caught an edge case you missed\n- **Automatic symbol planning** — Rune would have ensured `.purpose` coverage before you started\n- **Structured review** — the reviewer's two-stage protocol catches spec drift early\n- **Traceability** — the orchestration record links task → agents → decisions → code\n\nAs enforcement increases (balanced, strict), skipping orchestration triggers warnings or blocks. The system is designed to let you learn the value of orchestration before it becomes mandatory.\n\n### The Full Loop\n\nHere is the complete picture of what happens when you build a feature with Paradigm:\n\n```\nYou (Maestro)\n  │\n  ├─ \"Add a health check endpoint\"\n  │\n  ├─ Quick-check → GREENLIGHT\n  │\n  ├─ Rune → Symbol plan: #health-check component\n  │\n  ├─ Builder → src/routes/health.ts\n  │\n  ├─ Reviewer → Stage 1 pass, Stage 2 pass (3 findings: 0 blocking)\n  │\n  ├─ Doc → Updates .purpose with #health-check\n  │\n  ├─ Rune → Compliance report: 1 component, 1 aspect ✓\n  │\n  └─ Commit → feat(#health-check): add GET /health endpoint\n```\n\nThis loop — plan, build, review, document, validate — is the heartbeat of Paradigm development. Every feature, bug fix, and refactor follows the same pattern. The agents change, the complexity varies, but the loop is always the same.\n\n> **What's next:** PARA 101 covers the five symbols (#, $, ^, !, ~) and purpose files in depth. PARA 301 covers enforcement levels and operations. PARA 401 covers the orchestration mechanics behind what you just experienced.",
-      "keyConcepts": [
-        "Every task follows: quick-check → orchestrate → build → review → commit",
-        "Quick-check returns GREENLIGHT (proceed) or ESCALATE (needs full planning)",
-        "Reviewer runs two stages: spec compliance first, code quality only if spec passes",
-        "Commit messages use Symbols: trailer for automatic history tracking",
-        "Skipping orchestration is allowed on minimal enforcement but loses traceability and risk assessment"
-      ],
-      "quiz": [
-        {
-          "id": "q1",
-          "question": "You built a new API endpoint without running quick-check or orchestration. The code works fine. On minimal enforcement, what happens when you commit?",
-          "choices": {
-            "A": "The commit is blocked — orchestration is always required",
-            "B": "The commit succeeds but the stop hook warns that no orchestration record exists for the changed files",
-            "C": "Nothing — minimal enforcement has no checks",
-            "D": "The commit is reverted automatically",
-            "E": "Git rejects the commit because the pre-commit hook fails"
-          },
-          "correct": "B",
-          "explanation": "On minimal enforcement, orchestration-required is set to off, so the stop hook does not block. However, the purpose-coverage check (which is set to warn on minimal) may warn if you did not create a .purpose file for the new endpoint. The commit succeeds either way — minimal enforcement never blocks. But you have no orchestration record, no Rune compliance report, and no structured review."
-        },
-        {
-          "id": "q2",
-          "question": "During the build step, Rune creates a symbol plan with #health-check as a component. After the builder writes the code, Rune's compliance report says \"1 component, 0 aspects — blocking.\" Why is this a problem?",
-          "choices": {
-            "A": "Aspects are required for documentation completeness but have no real purpose",
-            "B": "Every component needs at least one aspect (rule, constraint, or configuration) — the 1:1 ratio means you must define what rules govern the health endpoint",
-            "C": "Rune made an error — health endpoints do not need aspects",
-            "D": "The builder should have created the aspect automatically",
-            "E": "This only matters on strict enforcement"
-          },
-          "correct": "B",
-          "explanation": "Rune enforces a 1:1 component-to-aspect ratio. Even a health endpoint has rules: response format, which checks it runs, timeout behavior, whether it includes dependency status. Defining an aspect like ~health-check-format forces you to document what the endpoint actually guarantees. This is not busywork — it is how Paradigm ensures every component has a documented contract."
-        },
-        {
-          "id": "q3",
-          "question": "The commit message for your feature reads: feat(#health-check): add GET /health endpoint. The Symbols: trailer says Symbols: #health-check. What does the post-commit hook do with this information?",
-          "choices": {
-            "A": "Nothing — the Symbols trailer is just for human readability",
-            "B": "It parses the Symbols trailer and records the commit in Paradigm's history system, linking the change to #health-check for traceability",
-            "C": "It validates that #health-check exists in a .purpose file",
-            "D": "It sends a notification to the agent team",
-            "E": "It automatically creates a changelog entry"
-          },
-          "correct": "B",
-          "explanation": "The post-commit hook parses the Symbols: trailer and records the commit in Paradigm's history system. This creates a traceable link: commit → symbols affected. Later, when someone asks \"what changed about #health-check?\" or runs paradigm_history_context, the answer includes this commit. The pre-commit hook handles index rebuilding; the post-commit hook handles history capture."
-        }
-      ]
-    }
-  ]
-}