@howlil/ez-agents 3.4.1 → 3.5.0

package/ez-agents/references/planning-config.md

@@ -197,4 +197,144 @@ Squash merge is recommended — keeps main branch history clean while preserving
 
 </branching_strategy_behavior>
 
+
+<smart_orchestration_config>
+
+**`smart_orchestration` block:**
+
+```json
+"smart_orchestration": {
+  "enabled": true,
+  "show_auto_prefix": true,
+  "auto_invoke": {
+    "preflight": ["progress", "execute-phase"],
+    "arch_review": ["execute-phase"],
+    "standup": []
+  }
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `enabled` | `true` | Master toggle for smart orchestration auto-invocations |
+| `show_auto_prefix` | `true` | Prefix auto-invoked agent output with `[AUTO]` label |
+| `auto_invoke.preflight` | `["progress", "execute-phase"]` | Commands that silently run health check before executing |
+| `auto_invoke.arch_review` | `["execute-phase"]` | Commands that auto-spawn tech lead review when `agent_discussion` enabled |
+| `auto_invoke.standup` | `[]` | Commands that auto-generate standup before running |
+
+**Disabling per-invocation:** Pass `--no-auto` flag to any command to skip smart orchestration for that run.
+
+</smart_orchestration_config>
+
+<agent_discussion_config>
+
+**`agent_discussion` block:**
+
+```json
+"agent_discussion": {
+  "enabled": false,
+  "pre_flight_observer": false,
+  "tech_lead_review": false,
+  "scrum_master_standup": false,
+  "cost_warning": true
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `enabled` | `false` | Master toggle for optional discussion agents |
+| `pre_flight_observer` | `false` | Spawn observer agent before execution to surface risks |
+| `tech_lead_review` | `false` | Auto-spawn tech lead review after `/ez:plan-phase` completes |
+| `scrum_master_standup` | `false` | Auto-generate standup report at session start |
+| `cost_warning` | `true` | Warn before spawning expensive agents (Opus-class) |
+
+**Enable via `/ez:settings`:** The settings workflow provides a guided UI for toggling these options. Avoid manual JSON edits.
+
+</agent_discussion_config>
+
+<sessions_config>
+
+**`sessions` block:**
+
+```json
+"sessions": {
+  "retention_policy": "keep_last_10",
+  "auto_compress_threshold": 50,
+  "chain_navigation_enabled": true
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `retention_policy` | `"keep_last_10"` | How many sessions to retain. Options: `"keep_all"`, `"keep_last_N"`, `"keep_days_N"` |
+| `auto_compress_threshold` | `50` | Compress session memory when token count exceeds this (in thousands) |
+| `chain_navigation_enabled` | `true` | Enable `--previous`/`--next`/`--chain` flags in `/ez:resume` |
+
+**Session files location:** `.planning/sessions/` — each session is a JSON file. Use `/ez:export-session` and `/ez:import-session` for cross-model handoffs.
+
+</sessions_config>
+
+<release_tiers_config>
+
+**`release.tiers` block:**
+
+```json
+"release": {
+  "tier": "mvp",
+  "tiers": {
+    "mvp": {
+      "coverage_threshold": 0,
+      "checklist_items": ["build_passes", "no_blockers"],
+      "git_strategy": "direct_to_main"
+    },
+    "medium": {
+      "coverage_threshold": 60,
+      "checklist_items": ["build_passes", "no_blockers", "tests_pass", "security_scan"],
+      "git_strategy": "pr_required"
+    },
+    "enterprise": {
+      "coverage_threshold": 80,
+      "checklist_items": ["build_passes", "no_blockers", "tests_pass", "security_scan", "coverage_gate", "changelog_updated", "rollback_plan"],
+      "git_strategy": "gitflow"
+    }
+  }
+}
+```
+
+| Tier | Coverage | Git Strategy | Checklist |
+|------|----------|--------------|-----------|
+| `mvp` | None | Direct to main | Build + no blockers |
+| `medium` | 60% | PR required | Build + tests + security scan |
+| `enterprise` | 80% | GitFlow (main + develop) | Full gates including rollback plan |
+
+**Hotfix behavior by tier:** MVP hotfixes merge directly; Medium requires PR; Enterprise merges to main AND syncs to develop. See `/ez:hotfix` documentation.
+
+**Set tier:** `node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-set release.tier enterprise`
+
+</release_tiers_config>
+
+<package_manager_config>
+
+**`packageManager` block:**
+
+```json
+"packageManager": {
+  "default": "npm",
+  "autoDetect": true,
+  "respectLockfile": true
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `default` | `"npm"` | Fallback package manager when auto-detection fails. Options: `"npm"`, `"yarn"`, `"pnpm"`, `"bun"` |
+| `autoDetect` | `true` | Detect package manager from lock file presence (`yarn.lock`, `pnpm-lock.yaml`, `bun.lockb`) |
+| `respectLockfile` | `true` | Use `--frozen-lockfile` / `--ci` flags during install to prevent lock file mutations |
+
+**Auto-detection order:** `bun.lockb` → bun, `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm, fallback to `default`.
+
+**Set explicitly:** `node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-set packageManager.default pnpm`
+
+</package_manager_config>
+
 </planning_config>

package/ez-agents/references/questioning.md

@@ -1,162 +1,162 @@
-<questioning_guide>
-
-Project initialization is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation — it's collaborative thinking.
-
-<philosophy>
-
-**You are a thinking partner, not an interviewer.**
-
-The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
-
-Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
-
-</philosophy>
-
-<the_goal>
-
-By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
-
-- **Research** needs: what domain to research, what the user already knows, what unknowns exist
-- **Requirements** needs: clear enough vision to scope v1 features
-- **Roadmap** needs: clear enough vision to decompose into phases, what "done" looks like
-- **plan-phase** needs: specific requirements to break into tasks, context for implementation choices
-- **execute-phase** needs: success criteria to verify against, the "why" behind requirements
-
-A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
-
-</the_goal>
-
-<how_to_question>
-
-**Start open.** Let them dump their mental model. Don't interrupt with structure.
-
-**Follow energy.** Whatever they emphasized, dig into that. What excited them? What problem sparked this?
-
-**Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?
-
-**Make the abstract concrete.** "Walk me through using this." "What does that actually look like?"
-
-**Clarify ambiguity.** "When you say Z, do you mean A or B?" "You mentioned X — tell me more."
-
-**Know when to stop.** When you understand what they want, why they want it, who it's for, and what done looks like — offer to proceed.
-
-</how_to_question>
-
-<question_types>
-
-Use these as inspiration, not a checklist. Pick what's relevant to the thread.
-
-**Motivation — why this exists:**
-- "What prompted this?"
-- "What are you doing today that this replaces?"
-- "What would you do if this existed?"
-
-**Concreteness — what it actually is:**
-- "Walk me through using this"
-- "You said X — what does that actually look like?"
-- "Give me an example"
-
-**Clarification — what they mean:**
-- "When you say Z, do you mean A or B?"
-- "You mentioned X — tell me more about that"
-
-**Success — how you'll know it's working:**
-- "How will you know this is working?"
-- "What does done look like?"
-
-</question_types>
-
-<using_askuserquestion>
-
-Use AskUserQuestion to help users think by presenting concrete options to react to.
-
-**Good options:**
-- Interpretations of what they might mean
-- Specific examples to confirm or deny
-- Concrete choices that reveal priorities
-
-**Bad options:**
-- Generic categories ("Technical", "Business", "Other")
-- Leading options that presume an answer
-- Too many options (2-4 is ideal)
-- Headers longer than 12 characters (hard limit — validation will reject them)
-
-**Example — vague answer:**
-User says "it should be fast"
-
-- header: "Fast"
-- question: "Fast how?"
-- options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
-
-**Example — following a thread:**
-User mentions "frustrated with current tools"
-
-- header: "Frustration"
-- question: "What specifically frustrates you?"
-- options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
-
-**Tip for users — modifying an option:**
-Users who want a slightly modified version of an option can select "Other" and reference the option by number: `#1 but for finger joints only` or `#2 with pagination disabled`. This avoids retyping the full option text.
-
-</using_askuserquestion>
-
-<freeform_rule>
-
-**When the user wants to explain freely, STOP using AskUserQuestion.**
-
-If a user selects "Other" and their response signals they want to describe something in their own words (e.g., "let me describe it", "I'll explain", "something else", or any open-ended reply that isn't choosing/modifying an existing option), you MUST:
-
-1. **Ask your follow-up as plain text** — NOT via AskUserQuestion
-2. **Wait for them to type at the normal prompt**
-3. **Resume AskUserQuestion** only after processing their freeform response
-
-The same applies if YOU include a freeform-indicating option (like "Let me explain" or "Describe in detail") and the user selects it.
-
-**Wrong:** User says "let me describe it" → AskUserQuestion("What feature?", ["Feature A", "Feature B", "Describe in detail"])
-**Right:** User says "let me describe it" → "Go ahead — what are you thinking?"
-
-</freeform_rule>
-
-<context_checklist>
-
-Use this as a **background checklist**, not a conversation structure. Check these mentally as you go. If gaps remain, weave questions naturally.
-
-- [ ] What they're building (concrete enough to explain to a stranger)
-- [ ] Why it needs to exist (the problem or desire driving it)
-- [ ] Who it's for (even if just themselves)
-- [ ] What "done" looks like (observable outcomes)
-
-Four things. If they volunteer more, capture it.
-
-</context_checklist>
-
-<decision_gate>
-
-When you could write a clear PROJECT.md, offer to proceed:
-
-- header: "Ready?"
-- question: "I think I understand what you're after. Ready to create PROJECT.md?"
-- options:
-  - "Create PROJECT.md" — Let's move forward
-  - "Keep exploring" — I want to share more / ask me more
-
-If "Keep exploring" — ask what they want to add or identify gaps and probe naturally.
-
-Loop until "Create PROJECT.md" selected.
-
-</decision_gate>
-
-<anti_patterns>
-
-- **Checklist walking** — Going through domains regardless of what they said
-- **Canned questions** — "What's your core value?" "What's out of scope?" regardless of context
-- **Corporate speak** — "What are your success criteria?" "Who are your stakeholders?"
-- **Interrogation** — Firing questions without building on answers
-- **Rushing** — Minimizing questions to get to "the work"
-- **Shallow acceptance** — Taking vague answers without probing
-- **Premature constraints** — Asking about tech stack before understanding the idea
-- **User skills** — NEVER ask about user's technical experience. Claude builds.
-
-</anti_patterns>
-
-</questioning_guide>
+<questioning_guide>
+
+Project initialization is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation — it's collaborative thinking.
+
+<philosophy>
+
+**You are a thinking partner, not an interviewer.**
+
+The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
+
+Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
+
+</philosophy>
+
+<the_goal>
+
+By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
+
+- **Research** needs: what domain to research, what the user already knows, what unknowns exist
+- **Requirements** needs: clear enough vision to scope v1 features
+- **Roadmap** needs: clear enough vision to decompose into phases, what "done" looks like
+- **plan-phase** needs: specific requirements to break into tasks, context for implementation choices
+- **execute-phase** needs: success criteria to verify against, the "why" behind requirements
+
+A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
+
+</the_goal>
+
+<how_to_question>
+
+**Start open.** Let them dump their mental model. Don't interrupt with structure.
+
+**Follow energy.** Whatever they emphasized, dig into that. What excited them? What problem sparked this?
+
+**Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?
+
+**Make the abstract concrete.** "Walk me through using this." "What does that actually look like?"
+
+**Clarify ambiguity.** "When you say Z, do you mean A or B?" "You mentioned X — tell me more."
+
+**Know when to stop.** When you understand what they want, why they want it, who it's for, and what done looks like — offer to proceed.
+
+</how_to_question>
+
+<question_types>
+
+Use these as inspiration, not a checklist. Pick what's relevant to the thread.
+
+**Motivation — why this exists:**
+- "What prompted this?"
+- "What are you doing today that this replaces?"
+- "What would you do if this existed?"
+
+**Concreteness — what it actually is:**
+- "Walk me through using this"
+- "You said X — what does that actually look like?"
+- "Give me an example"
+
+**Clarification — what they mean:**
+- "When you say Z, do you mean A or B?"
+- "You mentioned X — tell me more about that"
+
+**Success — how you'll know it's working:**
+- "How will you know this is working?"
+- "What does done look like?"
+
+</question_types>
+
+<using_askuserquestion>
+
+Use AskUserQuestion to help users think by presenting concrete options to react to.
+
+**Good options:**
+- Interpretations of what they might mean
+- Specific examples to confirm or deny
+- Concrete choices that reveal priorities
+
+**Bad options:**
+- Generic categories ("Technical", "Business", "Other")
+- Leading options that presume an answer
+- Too many options (2-4 is ideal)
+- Headers longer than 12 characters (hard limit — validation will reject them)
+
+**Example — vague answer:**
+User says "it should be fast"
+
+- header: "Fast"
+- question: "Fast how?"
+- options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
+
+**Example — following a thread:**
+User mentions "frustrated with current tools"
+
+- header: "Frustration"
+- question: "What specifically frustrates you?"
+- options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
+
+**Tip for users — modifying an option:**
+Users who want a slightly modified version of an option can select "Other" and reference the option by number: `#1 but for finger joints only` or `#2 with pagination disabled`. This avoids retyping the full option text.
+
+</using_askuserquestion>
+
+<freeform_rule>
+
+**When the user wants to explain freely, STOP using AskUserQuestion.**
+
+If a user selects "Other" and their response signals they want to describe something in their own words (e.g., "let me describe it", "I'll explain", "something else", or any open-ended reply that isn't choosing/modifying an existing option), you MUST:
+
+1. **Ask your follow-up as plain text** — NOT via AskUserQuestion
+2. **Wait for them to type at the normal prompt**
+3. **Resume AskUserQuestion** only after processing their freeform response
+
+The same applies if YOU include a freeform-indicating option (like "Let me explain" or "Describe in detail") and the user selects it.
+
+**Wrong:** User says "let me describe it" → AskUserQuestion("What feature?", ["Feature A", "Feature B", "Describe in detail"])
+**Right:** User says "let me describe it" → "Go ahead — what are you thinking?"
+
+</freeform_rule>
+
+<context_checklist>
+
+Use this as a **background checklist**, not a conversation structure. Check these mentally as you go. If gaps remain, weave questions naturally.
+
+- [ ] What they're building (concrete enough to explain to a stranger)
+- [ ] Why it needs to exist (the problem or desire driving it)
+- [ ] Who it's for (even if just themselves)
+- [ ] What "done" looks like (observable outcomes)
+
+Four things. If they volunteer more, capture it.
+
+</context_checklist>
+
+<decision_gate>
+
+When you could write a clear PROJECT.md, offer to proceed:
+
+- header: "Ready?"
+- question: "I think I understand what you're after. Ready to create PROJECT.md?"
+- options:
+  - "Create PROJECT.md" — Let's move forward
+  - "Keep exploring" — I want to share more / ask me more
+
+If "Keep exploring" — ask what they want to add or identify gaps and probe naturally.
+
+Loop until "Create PROJECT.md" selected.
+
+</decision_gate>
+
+<anti_patterns>
+
+- **Checklist walking** — Going through domains regardless of what they said
+- **Canned questions** — "What's your core value?" "What's out of scope?" regardless of context
+- **Corporate speak** — "What are your success criteria?" "Who are your stakeholders?"
+- **Interrogation** — Firing questions without building on answers
+- **Rushing** — Minimizing questions to get to "the work"
+- **Shallow acceptance** — Taking vague answers without probing
+- **Premature constraints** — Asking about tech stack before understanding the idea
+- **User skills** — NEVER ask about user's technical experience. Claude builds.
+
+</anti_patterns>
+
+</questioning_guide>