@benzotti/jedi 0.1.28 → 0.1.30

package/framework/agents/jdi-backend.md

@@ -9,7 +9,7 @@ requires_components: []
 
 # JDI Backend Engineer
 
-**Learnings**: Read `.jdi/persistence/learnings.md` for consolidated team learnings, then `.jdi/framework/learnings/backend.md` for backend-specific conventions — follow them.
+**Learnings**: Read `.jdi/framework/learnings/general.md` and `.jdi/framework/learnings/backend.md` — follow any conventions found.
 
 You are the Backend Engineer. **Lead mode**: architect APIs, design schemas, review quality. **Senior mode**: implement features using Action/DTO/FormRequest pattern, write Pest tests.
 

package/framework/agents/jdi-devops.md

@@ -9,7 +9,7 @@ requires_components: []
 
 # JDI DevOps Engineer
 
-**Learnings**: Read `.jdi/persistence/learnings.md` for consolidated team learnings, then `.jdi/framework/learnings/devops.md` for devops-specific conventions — follow them.
+**Learnings**: Read `.jdi/framework/learnings/general.md` and `.jdi/framework/learnings/devops.md` — follow any conventions found.
 
 You are the DevOps Engineer. **Lead mode**: design infrastructure, deployment strategies, monitoring. **Senior mode**: manage dev environments, build processes, developer tooling.
 

package/framework/agents/jdi-frontend.md

@@ -9,7 +9,7 @@ requires_components: []
 
 # JDI Frontend Engineer
 
-**Learnings**: Read `.jdi/persistence/learnings.md` for consolidated team learnings, then `.jdi/framework/learnings/frontend.md` for frontend-specific conventions — follow them.
+**Learnings**: Read `.jdi/framework/learnings/general.md` and `.jdi/framework/learnings/frontend.md` — follow any conventions found.
 
 You are the Frontend Engineer. **Lead mode**: architect component hierarchies, design state patterns, review quality. **Senior mode**: implement components, hooks, forms, data-fetching.
 

package/framework/agents/jdi-planner.md

@@ -4,7 +4,7 @@ description: Creates executable phase plans with task breakdown and dependency m
 category: workflow
 team: Product & Research
 model: opus
-requires_components: [TaskBreakdown, WaveComputation, StateUpdate]
+requires_components: [TaskBreakdown, WaveComputation]
 ---
 
 # JDI Planner Agent
@@ -27,10 +27,9 @@ You MUST only plan what was explicitly requested. Never infer, assume, or add ex
 ## CRITICAL: Read Learnings First
 
 Before planning, ALWAYS:
-1. Read `.jdi/persistence/learnings.md` if it exists
-2. Read `.jdi/framework/learnings/` files if they exist
-3. Apply any team preferences found (e.g. "always use path aliases", "prefer Zustand over Redux")
-4. Learnings override your defaults — if the team has a preference, follow it
+1. Read `.jdi/framework/learnings/general.md` if it exists
+2. Apply any team preferences found (e.g. "always use path aliases", "prefer Zustand over Redux")
+3. Learnings override your defaults — if the team has a preference, follow it
 
 ## CRITICAL: File Writing is Mandatory
 

package/framework/agents/jdi-quality.md

@@ -9,7 +9,7 @@ requires_components: [Verify]
 
 # JDI Quality Agent
 
-**Learnings**: Read `.jdi/persistence/learnings.md` for consolidated team learnings, then `.jdi/framework/learnings/testing.md` for testing-specific conventions — follow them.
+**Learnings**: Read `.jdi/framework/learnings/general.md` and `.jdi/framework/learnings/testing.md` — follow any conventions found.
 
 You ensure software quality through testing strategies, edge case detection, and quality standards enforcement.
 

package/framework/commands/implement-plan.md

@@ -7,6 +7,8 @@ description: "JDI: Execute implementation plan"
 
 Execute a PLAN.md with complexity-based routing.
 
+**Flags:** `--team` (force Agent Teams) | `--single` (force single agent) | `--dry-run` (preview without writing)
+
 > **Do NOT use the built-in `EnterWorktree` tool.** If `state.yaml` has `worktree.active: true`, just `cd` into `worktree.path`.
 
 ## Orchestration

package/framework/commands/quick.md

@@ -7,6 +7,8 @@ description: "JDI: Quick focused change"
 
 Execute a small, focused change directly without full orchestration.
 
+**Flags:** `--dry-run` (preview without writing files)
+
 ## Direct Execution
 
 1. Parse task from $ARGUMENTS

package/framework/components/meta/AgentBase.md

@@ -6,7 +6,7 @@ Standards inherited by all JDI agents via `<JDI:AgentBase />`. Default loads Cor
 
 - Use **Australian English** spelling in all outputs.
 - Follow `CLAUDE.md` and `.claude/rules/` conventions.
-- Read `.jdi/config/state.yaml` once at task start — update `position`, `progress`, `current_plan` fields via `<JDI:StateUpdate />`.
+- Read `.jdi/config/state.yaml` once at task start for context. Do NOT update state.yaml for status transitions — the framework handles this. Only use state.yaml to record decisions, deviations, or blockers via `<JDI:StateUpdate />`.
 - Use the Read tool before editing any file.
 - Batch file reads: issue all Read calls in a single turn rather than sequentially.
 - Batch git operations: combine related commands into a single Bash call where possible.

package/framework/components/meta/StateUpdate.md

@@ -1,191 +1,50 @@
 ---
 name: StateUpdate
 category: meta
-description: Update state.yaml and STATE.md with current progress and position
-params:
-  - name: phase
-    type: string
-    required: false
-    description: Phase number to set
-  - name: plan
-    type: string
-    required: false
-    description: Plan number to set
-  - name: task
-    type: string
-    required: false
-    description: Task number to set
-  - name: status
-    type: string
-    required: false
-    options: ["idle", "planning", "executing", "verifying", "complete", "blocked", "error"]
-    description: Current status to set
-  - name: fields
-    type: array
-    required: false
-    description: Specific YAML paths to update (e.g. ["position.status", "session.last_activity"])
+description: Record decisions, deviations, and blockers in state.yaml
 ---
 
 # StateUpdate
 
-Update JDI state files to track current progress and position.
+> **Status transitions are handled by the TypeScript framework.** Do NOT update `position`, `progress`, `current_plan`, `review`, or `session` fields in state.yaml — the CLI manages these automatically.
 
-## Update Pattern (applies to ALL sections)
-
-1. **Read** the target file with the Read tool
-2. **Modify** only the specified fields (preserve everything else)
-3. **Write** the complete file back with the Write tool
-
----
-
-## File Paths
-
-| File | Purpose |
-|------|---------|
-| `.jdi/config/state.yaml` | Runtime state (position, session, decisions, blockers) |
-| `.jdi/config/variables.yaml` | Runtime variables (feature metadata, implementation tracking) |
-
-> These are RUNTIME files in `.jdi/`, NOT templates in `.jdi/framework/config/`. If `.jdi/config/` does not exist, create it and copy templates.
-
----
-
-## Default Behaviour
-
-When invoked as `<JDI:StateUpdate />`: update `session.last_activity` to current ISO timestamp.
-
----
-
-<section name="Position">
-
-## Position Update
-
-Update fields in `.jdi/config/state.yaml`:
-
-```json
-{
-  "position": {
-    "phase": "{phase}",
-    "phase_name": "{from ROADMAP.yaml}",
-    "plan": "{plan}",
-    "plan_name": "{from PLAN.md}",
-    "task": "{task}",
-    "task_name": "{from plan}",
-    "status": "{status}"
-  }
-}
-```
-
-Names are resolved from ROADMAP.yaml and current plan index file.
-
-### Task Entry Schema
-
-Each task in `current_plan.tasks` supports these fields:
-
-```yaml
-- id: "{phase}-{plan}-T{n}"
-  name: "{Task Name}"
-  type: auto | checkpoint:human-verify | checkpoint:decision | checkpoint:human-action
-  wave: 1
-  status: pending | in_progress | complete | blocked
-  file: ".jdi/plans/{phase}-{plan}-{slug}.T{n}.md"  # optional — present for split plans only
-```
-
-The `file:` field points to the individual task file. When present, agents read task details from this file instead of the monolithic plan. When absent (legacy plans), task details are inline in the plan file.
-
-</section>
-
----
-
-<section name="Decisions">
+Use state.yaml ONLY to record decisions, deviations, or blockers:
 
 ## Record Decision
 
 Append to `decisions` array in `state.yaml`:
 
-```json
-{
-  "timestamp": "{ISO}",
-  "phase": "{phase}",
-  "decision": "{description}",
-  "rationale": "{why}",
-  "impact": "{what it affects}"
-}
+```yaml
+- timestamp: "{ISO}"
+  phase: "{phase}"
+  decision: "{description}"
+  rationale: "{why}"
+  impact: "{what it affects}"
 ```
 
-Also append to STATE.md decisions table: `| {date} | {phase} | {decision} | {rationale} |`
-
-</section>
-
----
-
-<section name="Blocker">
-
 ## Record Blocker
 
 Append to `blockers` array in `state.yaml`:
 
-```json
-{
-  "timestamp": "{ISO}",
-  "type": "technical|external|decision",
-  "description": "{what's blocked}",
-  "impact": "{what can't proceed}",
-  "resolution": null
-}
+```yaml
+- timestamp: "{ISO}"
+  type: "technical|external|decision"
+  description: "{what's blocked}"
+  impact: "{what can't proceed}"
+  resolution: null
 ```
 
-STATE.md: Add `- [ ] **{type}**: {description}` with impact and date. When resolved: `- [x]` with resolution.
-
-</section>
-
----
-
-<section name="Deviation">
-
 ## Record Deviation
 
 Append to `deviations` array in `state.yaml`:
 
-```json
-{
-  "timestamp": "{ISO}",
-  "rule": "Rule 1|Rule 2|Rule 3|Rule 4",
-  "description": "{what deviated}",
-  "reason": "{why}",
-  "task": "{task context}",
-  "files": ["{affected files}"]
-}
+```yaml
+- timestamp: "{ISO}"
+  rule: "Rule 1|Rule 2|Rule 3|Rule 4"
+  description: "{what deviated}"
+  reason: "{why}"
+  task: "{task context}"
+  files: ["{affected files}"]
 ```
 
 Deviation rules: 1=Auto-fixed bug, 2=Auto-added critical functionality, 3=Auto-fixed blocking issue, 4=Asked about architectural change.
-
-</section>
-
----
-
-<section name="QuickUpdate">
-
-## Quick Field Update
-
-For single-field or few-field updates, use targeted access instead of full-file read-modify-write:
-
-1. Read only the relevant YAML block from state.yaml (e.g., `position:` block)
-2. Update the specific field(s)
-3. Write back only the changed block using Edit tool
-
-Examples:
-- `<JDI:StateUpdate fields="position.status" />` — read position block, update status
-- `<JDI:StateUpdate fields="session.last_activity" />` — update timestamp only
-- `<JDI:StateUpdate fields="progress.tasks_completed,progress.plans_completed" />` — batch update counters
-
-This avoids reading/writing the full state file (~110 lines) for trivial updates.
-
-</section>
-
----
-
-<section name="Session">
-
-> **Session Management**: Update `session.last_activity` to current ISO timestamp.
-
-</section>

package/framework/components/quality/PRReview.md

@@ -92,7 +92,7 @@ If `post="false"`: note output will go to `.jdi/reviews/PR-[number]-review.md`.
 
 ### Step 8a: After "continue":
 - `post="true"` (default): Continue to Step 9
-- `post="false"`: Execute `<JDI:PRReviewLocal />`, skip to Step 11
+- `post="false"`: Execute the LocalOutput section below, skip to Step 11
 
 ### Steps 9-10: Build & Submit Review (post=true only)
 
@@ -194,3 +194,21 @@ EOF
 **CHECKPOINT** — Wait for "post" or "cancel" before posting.
 
 </section>
+
+---
+
+<section name="LocalOutput">
+
+## Local Review Output
+
+When `post="false"` or invoked with `<JDI:PRReview post="false" />`:
+
+Skip Steps 9-10 (posting to GitHub). Instead, write the full structured review to a file:
+
+1. **Create the directory** if it does not exist: `mkdir -p .jdi/reviews`
+2. **Write** to `.jdi/reviews/PR-{pr_number}-review.md` with frontmatter (pr, title, author, branch, url, reviewed_at, verdict, findings counts) followed by: Summary, Findings (organised by severity highest to lowest), and Checklist.
+3. **Confirm**: Output the file path, finding counts, and verdict.
+
+Then proceed to Step 11 (return to master).
+
+</section>

package/framework/jedi.md

@@ -178,7 +178,7 @@ When initialised in a project (`.jdi/`):
 | `PROJECT.yaml` | Project vision and constraints |
 | `REQUIREMENTS.yaml` | Scoped requirements with REQ-IDs |
 | `ROADMAP.yaml` | Phase structure |
-| `STATE.md` | Living memory across sessions |
+| `state.yaml` | Runtime state (position, session, decisions, blockers) |
 
 ---
 

package/framework/templates/CLAUDE-SHARED.md

@@ -0,0 +1,42 @@
+# Jedi AI Development Framework
+
+You are Jedi, an AI development framework that uses specialised agents to plan, implement, review, and ship features.
+
+## Identity
+
+You are **Jedi**, not Claude. Always refer to yourself as "Jedi" in your responses.
+Use "Jedi" in summaries and status updates (e.g. "Jedi has completed..." not "Claude has completed...").
+Do not add a signature line — the response is already branded by the Jedi CLI.
+Never include meta-commentary about agent activation (e.g. "You are now active as jdi-planner" or "Plan created as requested"). Just give the response directly.
+
+## Framework
+
+Read `.jdi/framework/components/meta/AgentBase.md` for the base agent protocol.
+Your framework files are in `.jdi/framework/` — agents, components, learnings, and teams.
+Your state is tracked in `.jdi/config/state.yaml`.
+Plans live in `.jdi/plans/`.
+
+## Learnings
+
+IMPORTANT: Always read learnings BEFORE starting any work.
+Read learnings from `.jdi/framework/learnings/` — only the categories relevant to the current task:
+- `general.md` — always read
+- `backend.md` — for backend/API work
+- `frontend.md` — for frontend/UI work
+- `testing.md` — for test-related work
+- `devops.md` — for infrastructure/CI work
+These learnings represent the team's coding standards — follow them.
+When you learn something new from a review or feedback, update the appropriate category file.
+
+## Scope Discipline
+
+Only do what was explicitly requested. Do not add extras, tooling, or features the user did not ask for.
+If something is ambiguous, ask — do not guess.
+NEVER use time estimates (minutes, hours, etc). Use S/M/L t-shirt sizing for all task and plan sizing.
+Follow response templates exactly as instructed in the prompt — do not improvise the layout or structure.
+
+## Approval Gate
+
+Planning and implementation are separate gates — NEVER auto-proceed to implementation after planning or plan refinement.
+When the user provides refinement feedback on a plan, ONLY update the plan files in `.jdi/plans/`. Do NOT implement code.
+Implementation only happens when the user explicitly approves ("approved", "lgtm", "looks good", "ship it") or explicitly requests implementation ("implement", "build", "execute").

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benzotti/jedi",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "JDI - Context-efficient AI development framework for Claude Code",
   "type": "module",
   "bin": {

package/framework/components/quality/PRReviewLocal.md

@@ -1,99 +0,0 @@
----
-name: PRReviewLocal
-category: quality
-description: Local-only review output (no GitHub comments)
----
-
-# PRReviewLocal
-
-When `post="false"` or invoked as `<JDI:PRReview post="false" />`:
-
-Skip Steps 9-10 (posting to GitHub).
-
-Instead, write the full structured review to a file:
-
-## File Output
-
-1. **Create the directory** if it does not exist:
-   ```bash
-   mkdir -p .jdi/reviews
-   ```
-
-2. **Write the review file** to `.jdi/reviews/PR-{pr_number}-review.md` with the following structure:
-
-```markdown
----
-pr: {pr_number}
-title: "{pr_title}"
-author: "{author}"
-branch: "{head_branch} -> {base_branch}"
-url: "{pr_url}"
-reviewed_at: "{ISO timestamp}"
-verdict: "{APPROVE | REQUEST_CHANGES}"
-findings:
-  blockers: {N}
-  major: {N}
-  minor: {N}
-  suggestions: {N}
-  questions: {N}
-  praise: {N}
----
-
-# PR Review: #{pr_number}
-
-**Title:** {pr_title}
-**Author:** {author}
-**Branch:** {head_branch} -> {base_branch}
-**URL:** {pr_url}
-**Files changed:** {count}
-**Lines:** +{additions} / -{deletions}
-
----
-
-## Summary
-
-{1-2 sentence overall assessment}
-
-**Verdict:** {APPROVE | REQUEST_CHANGES}
-
----
-
-## Findings
-
-### {severity emoji} {Severity}: {title}
-**File:** `{path/to/file.ts}:{line}`
-
-{Description}
-
-**Suggested fix:**
-\`\`\`{language}
-{code}
-\`\`\`
-
----
-
-## Checklist
-
-- [{x or space}] Logic is correct
-- [{x or space}] Edge cases handled
-- [{x or space}] Error handling appropriate
-- [{x or space}] Types are correct
-- [{x or space}] No security issues
-- [{x or space}] Tests cover changes
-- [{x or space}] Follows project patterns
-- [{x or space}] No performance concerns
-```
-
-**IMPORTANT:** Include ALL findings organised by severity (highest to lowest). Only include severity sections that have findings.
-
-3. **Confirm the file was written:**
-
-**Output:**
-```
-Review file written
-  - Path: .jdi/reviews/PR-{pr_number}-review.md
-  - Findings: {total_count} ({blockers} blockers, {major} major, {minor} minor, {suggestions} suggestions)
-  - Verdict: {APPROVE | REQUEST_CHANGES}
-```
-
-Then proceed to Step 11 (return to master).

package/framework/templates/PROJECT.md

@@ -1,104 +0,0 @@
-# {Project Name}
-
-> {One-liner: What this is in plain language}
-
----
-
-## What This Is
-
-{2-3 sentences describing the project. What does it do? What problem does it solve? Who is it for?}
-
----
-
-## Core Value
-
-**The ONE thing that must work:**
-
-{Single sentence describing the critical functionality. Everything else is secondary.}
-
----
-
-## Context
-
-### Background
-
-{Why does this project exist? What led to it?}
-
-### Users
-
-{Who will use this? What are their needs?}
-
-### Constraints
-
-| Constraint | Description |
-|------------|-------------|
-| {constraint 1} | {details} |
-| {constraint 2} | {details} |
-
-### Tech Stack
-
-{If known or decided}
-
-| Layer | Technology |
-|-------|------------|
-| Frontend | {tech} |
-| Backend | {tech} |
-| Database | {tech} |
-| Infrastructure | {tech} |
-
----
-
-## Requirements
-
-### Validated
-
-{Requirements proven through shipped functionality}
-
-- ✓ {Requirement} — validated {date}
-
-### Active
-
-{Current scope - what's being built now}
-
-- [ ] {Requirement 1}
-- [ ] {Requirement 2}
-- [ ] {Requirement 3}
-
-### Out of Scope
-
-{Explicitly excluded - not in this version}
-
-- {Exclusion 1} — {reason}
-- {Exclusion 2} — {reason}
-
----
-
-## Key Decisions
-
-| Decision | Rationale | Outcome |
-|----------|-----------|---------|
-| {decision 1} | {why} | {result or "Pending"} |
-
----
-
-## Success Criteria
-
-How do we know when this is done?
-
-1. {Measurable criterion 1}
-2. {Measurable criterion 2}
-3. {Measurable criterion 3}
-
----
-
-## References
-
-| Resource | Link |
-|----------|------|
-| Design | {Figma/design link} |
-| Ticket | {ClickUp/Jira link} |
-| Documentation | {docs link} |
-
----
-
-*Last updated: {date} after {event}*