pi-crew 0.5.24 → 0.6.0

package/CHANGELOG.md

@@ -1401,3 +1401,37 @@ correctness+error-handling, and performance+architecture audits across 77 source
 
 ### CI
 - `.github/workflows/ci.yml`: typecheck step re-enabled (was disabled since v0.3.x)
+
+## [0.6.0] — Source Tour Patterns Implementation (2026-06-04)
+
+### Highlights
+- **15 patterns** implemented from 63-repo source tour (2,267 LOC)
+- All patterns pass TypeScript strict mode with 0 errors
+- 37 skills (including new council skill)
+
+### Tier 1 — Quick Wins
+- **Council skill** (Pattern 5): 3 adversarial roles for critical decisions
+- **6 lifecycle hooks** (Pattern 12): after_run_complete, after_task_complete, session hooks
+- **3-tier convention** (Pattern 13): Command→Agent→Skill documentation + effort field
+- **Pre-step scripts** (Pattern 2): Deterministic scripts before LLM dispatch
+- **Chain DSL parser** (Pattern 8): step1 -> parallel(step2, step3) -> step4
+
+### Tier 2 — Medium-Term
+- **DAG enhancements** (Pattern 7): findBlockedTasks, getBlockingTasks, topologicalSort
+- **Drift detection** (Pattern 10): 5 detectors, 2-pass reconciliation
+- **Hash-based task IDs** (Pattern 11): Base36 + adaptive length + hierarchical
+- **Iterative retrieval** (Pattern 6): Score → converge → refine loop
+- **Intercom bridge** (Pattern 9): Worker→orchestrator escalation queue
+- **Plan templates** (Pattern 15): Built-in standard-review and full-implementation
+
+### Tier 3 — Long-Term
+- **Phase-gated intermediates** (Pattern 1): Disk-persistent step outputs
+- **Incremental fingerprinting** (Pattern 3): Content hash + structural signature
+- **4-tier memory** (Pattern 4): Working→Episodic→Semantic→Procedural with Ebbinghaus decay
+- **Observation system** (Pattern 14): Capture→compress→re-inject with privacy tags
+
+### Stats
+- Test suite: 2698 pass + 1 skip, 0 fail
+- TypeScript: 0 errors
+- Skills: 37/37 PASS
+- New modules: 11 files, 2,267 LOC

package/docs/patterns/command-agent-skill.md

@@ -0,0 +1,71 @@
+# Command → Agent → Skill: 3-Tier Pattern
+
+> **Origin**: `source/claude-code-best-practice/CLAUDE.md`
+> **Applicable to**: pi-crew v0.5.25+
+
+## The 3 Tiers
+
+```
+User invokes → [Command] → [Agent] → [Skill]
+                entry       worker     reusable
+                point       + tools    capability
+```
+
+### Tier 1: Command (Entry Point)
+- Maps user intent to an agent
+- Defined in workflow `.md` files as a step
+- Example: `team action='run' team='review'`
+
+### Tier 2: Agent (Specialized Worker)
+- Has a system prompt, model, tools, skills, effort level
+- Defined as `.md` file with YAML frontmatter in `agents/` directory
+- Example:
+
+```markdown
+---
+name: security-reviewer
+description: Chief Security Officer who finds OWASP Top 10 threats
+tools: read, bash, edit
+model: claude-sonnet-4-20250514
+effort: high
+skills: safe-bash, security-review
+maxTurns: 30
+contextMode: fresh
+---
+
+You are a Chief Security Officer...
+```
+
+### Tier 3: Skill (Reusable Capability)
+- A `SKILL.md` file with instructions + operating rules
+- Injected into agent context at dispatch time
+- Example: `skills/safe-bash/SKILL.md`
+
+## How to Compose
+
+1. **Define the skill** — Create `skills/my-skill/SKILL.md`
+2. **Define the agent** — Create `agents/my-agent.md` referencing the skill
+3. **Define the workflow** — Create `workflows/my-workflow.workflow.md` referencing the agent as a step
+
+```yaml
+# workflows/my-workflow.workflow.md
+steps:
+  - name: analyze
+    agent: my-agent
+    # The agent loads my-skill automatically
+```
+
+## Agent YAML Frontmatter Reference
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Agent identifier |
+| `description` | string | One-line description for routing |
+| `tools` | csv | Tools the agent can use |
+| `model` | string | Model override |
+| `skills` | csv | Skills to inject |
+| `effort` | `low`/`medium`/`high` | Work effort level |
+| `maxTurns` | number | Maximum conversation turns |
+| `contextMode` | `fresh`/`fork` | Context inheritance |
+| `loadMode` | `essential`/`lean` | Tool loading strategy |
+| `thinking` | string | Thinking level override |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.5.24",
+  "version": "0.6.0",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/skills/council/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: council
+description: >
+  Spawn 3 adversarial subagents (Skeptic, Pragmatist, Critic) to evaluate a decision,
+  architecture choice, or plan. Anti-anchoring: each role receives ONLY the question,
+  not conversation history. Aggregates votes into consensus recommendation with dissent tracking.
+  Use when facing critical decisions, architecture choices, security tradeoffs, or plan reviews
+  where single-perspective analysis is insufficient.
+origin: ECC/skills/council
+---
+
+# Council Pattern — Adversarial Multi-Perspective Decision Making
+
+## When to Use
+
+- Evaluating architecture decisions with significant tradeoffs
+- Reviewing security-sensitive design choices
+- Validating implementation plans before execution
+- Resolving ambiguity where multiple valid approaches exist
+- Deciding whether to build, buy, or extend
+
+## Prerequisites
+
+- A clearly formulated question or decision to evaluate
+- Sufficient context about the system for meaningful analysis
+
+## Operating Rules
+
+1. You MUST spawn exactly 3 subagents with isolated context (fresh, not forked)
+2. Each subagent receives ONLY the question — NO conversation history (anti-anchoring)
+3. You MUST NOT influence any subagent's analysis direction
+4. You MUST record all 3 votes before forming consensus
+5. You MUST include dissent in the final recommendation
+
+## Workflow
+
+### Step 1: Formulate the Question
+
+Write a clear, neutral question that includes:
+- The decision to be made
+- Relevant constraints (performance, security, timeline)
+- Available options (if known)
+- What "success" looks like
+
+DO NOT bias the question toward any particular answer.
+
+### Step 2: Spawn 3 Council Members
+
+Launch 3 parallel subagents with these EXACT roles:
+
+**Skeptic** (Goal: Find flaws):
+```
+You are the Skeptic on a council evaluating: [QUESTION]
+
+Your role: Find every possible flaw, risk, and failure mode.
+- Challenge assumptions
+- Identify edge cases that break the proposed approach
+- Focus on what could go WRONG
+- Rate your confidence (0.0-1.0) and give a PRO/CON/ABSTAIN position
+- Provide your top 3 risks
+
+Output format:
+Position: PRO | CON | ABSTAIN
+Confidence: 0.0-1.0
+Reasoning: [your analysis]
+Top 3 Risks: [list]
+```
+
+**Pragmatist** (Goal: Evaluate tradeoffs):
+```
+You are the Pragmatist on a council evaluating: [QUESTION]
+
+Your role: Weigh practical tradeoffs objectively.
+- Consider implementation cost, maintenance burden, team impact
+- Evaluate time-to-value and opportunity cost
+- Compare against realistic alternatives
+- Rate your confidence (0.0-1.0) and give a PRO/CON/ABSTAIN position
+
+Output format:
+Position: PRO | CON | ABSTAIN
+Confidence: 0.0-1.0
+Reasoning: [your analysis]
+Alternatives Considered: [list]
+```
+
+**Critic** (Goal: Stress-test reasoning):
+```
+You are the Critic on a council evaluating: [QUESTION]
+
+Your role: Stress-test the logical foundations of each possible answer.
+- Identify logical fallacies in common arguments for/against
+- Check if the question itself contains hidden assumptions
+- Evaluate whether the stated constraints are real or assumed
+- Rate your confidence (0.0-1.0) and give a PRO/CON/ABSTAIN position
+
+Output format:
+Position: PRO | CON | ABSTAIN
+Confidence: 0.0-1.0
+Reasoning: [your analysis]
+Hidden Assumptions: [list]
+```
+
+### Step 3: Aggregate Votes
+
+Collect all 3 responses. Compute consensus:
+
+| Vote Pattern | Consensus Level | Action |
+|---|---|---|
+| 3 PRO | **Strong accept** | Proceed with high confidence |
+| 2 PRO, 1 CON | **Weak accept** | Proceed, but address CON dissent |
+| 2 PRO, 1 ABSTAIN | **Accept with uncertainty** | Proceed, investigate ABSTAIN concerns |
+| 1 PRO, 1 CON, 1 ABSTAIN | **No consensus** | Reformulate question or gather more data |
+| 2 CON, 1 PRO | **Weak reject** | Do not proceed; explore alternatives |
+| 3 CON | **Strong reject** | Reject; fundamentally rethink approach |
+
+### Step 4: Output Recommendation
+
+```markdown
+## Council Decision: [Question Summary]
+
+### Votes
+| Role | Position | Confidence |
+|------|----------|------------|
+| Skeptic | PRO/CON/ABSTAIN | 0.X |
+| Pragmatist | PRO/CON/ABSTAIN | 0.X |
+| Critic | PRO/CON/ABSTAIN | 0.X |
+
+### Consensus: [STRONG ACCEPT | WEAK ACCEPT | NO CONSENSUS | WEAK REJECT | STRONG REJECT]
+
+### Recommendation
+[One-paragraph synthesis]
+
+### Key Insights
+- [Best point from Skeptic]
+- [Best point from Pragmatist]
+- [Best point from Critic]
+
+### Dissent
+[Summary of any dissenting opinions and why they were overruled or remain unresolved]
+
+### Action Items
+- [ ] [Specific next step 1]
+- [ ] [Specific next step 2]
+```
+
+## Anti-Patterns
+
+- DO NOT spawn fewer than 3 roles
+- DO NOT share one subagent's analysis with another (contamination)
+- DO NOT phrase the question to favor a specific outcome
+- DO NOT override the council's consensus without documented justification
+- DO NOT use council for trivial decisions (wastes resources)
+
+## Enforcement — Council Gate
+
+Before finalizing a council result, verify:
+
+- [ ] All 3 roles spawned with isolated (fresh) context
+- [ ] Each role received ONLY the question, no prior conversation
+- [ ] All 3 votes recorded with confidence scores
+- [ ] Consensus level computed from vote pattern
+- [ ] Dissent explicitly documented (not hidden)
+- [ ] Recommendation includes actionable next steps

package/src/agents/agent-config.ts

@@ -36,6 +36,8 @@ export interface AgentConfig {
 	contextMode?: "fresh" | "fork";
 	/** Maximum turns for this agent. Overrides runtime config if set. */
 	maxTurns?: number;
+	/** Effort level for this agent. Controls how much work the agent puts in. */
+	effort?: "low" | "medium" | "high";
 	/** Tools to explicitly forbid for this agent. Takes precedence over allowedTools. */
 	disallowedTools?: string[];
 	disabled?: boolean;

package/src/agents/discover-agents.ts

@@ -376,6 +376,7 @@ function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig |
 		defaultTools: frontmatter.defaultTools !== undefined ? parseCsv(frontmatter.defaultTools) ?? null : undefined,
 		contextMode: parseContextMode(frontmatter.contextMode),
 		maxTurns: (() => { const n = Number.parseInt(frontmatter.maxTurns, 10); return Number.isFinite(n) && n > 0 ? n : undefined; })(),
+		effort: frontmatter.effort === "low" || frontmatter.effort === "medium" || frontmatter.effort === "high" ? frontmatter.effort : undefined,
 		disabled: frontmatter.disabled === "true" || frontmatter.enabled === "false",
 		routing: triggers || useWhen || avoidWhen || cost || category ? { triggers, useWhen, avoidWhen, cost, category } : undefined,
 		};

package/src/hooks/types.ts

@@ -1,6 +1,8 @@
 export type HookName =
 	| "before_run_start"
+	| "after_run_complete"
 	| "before_task_start"
+	| "after_task_complete"
 	| "task_result"
 	| "before_cancel"
 	| "before_retry"
@@ -8,8 +10,20 @@ export type HookName =
 	| "before_cleanup"
 	| "before_publish"
 	| "session_before_switch"
+	| "session_after_connect"
+	| "session_after_disconnect"
 	| "run_recovery";
 
+/**
+ * Hook exit codes inspired by claude-mem's lifecycle architecture:
+ * - 0 = allow (success)
+ * - 1 = warn (non-blocking error, continue)
+ * - 2 = block (blocking error, stop)
+ */
+export const HOOK_EXIT_SUCCESS = 0 as const;
+export const HOOK_EXIT_WARN = 1 as const;
+export const HOOK_EXIT_BLOCK = 2 as const;
+
 export type HookMode = "blocking" | "non_blocking";
 export type HookOutcome = "allow" | "block" | "modify" | "diagnostic";
 

package/src/runtime/chain-parser.ts

@@ -0,0 +1,192 @@
+/**
+ * Chain/Parallel DSL Parser — parses workflow chain expressions.
+ *
+ * Syntax:
+ *   step1 -> step2 -> parallel(step3, step4) -> step5
+ *   step1:3 -> step2 --with-context -> step3
+ *   parallel(a, b, parallel(c, d)) -> e
+ *
+ * Pattern origin: pi-prompt-template-model chain-parser.ts
+ */
+
+export interface ChainStep {
+	/** Step name (maps to agent or workflow step ID) */
+	name: string;
+	/** Nested parallel group */
+	parallel?: ChainStep[];
+	/** Loop count (default: 1) */
+	loopCount?: number;
+	/** Pass predecessor output as context */
+	withContext?: boolean;
+	/** Positional arguments */
+	args?: string[];
+}
+
+/**
+ * Parse a chain DSL string into an AST.
+ *
+ * @throws {Error} on syntax errors (unclosed parens, empty names, etc.)
+ */
+export function parseChainDSL(input: string): ChainStep[] {
+	const tokens = tokenize(input);
+	const parser = new ChainParser(tokens);
+	return parser.parse();
+}
+
+// ── Tokenizer ────────────────────────────────────────────────────────────
+
+type TokenType = "NAME" | "ARROW" | "LPAREN" | "RPAREN" | "COMMA" | "COLON" | "NUMBER" | "FLAG" | "QUOTED";
+
+interface Token {
+	type: TokenType;
+	value: string;
+}
+
+function tokenize(input: string): Token[] {
+	const tokens: Token[] = [];
+	let i = 0;
+
+	while (i < input.length) {
+		// Skip whitespace
+		if (/\s/.test(input[i]!)) { i++; continue; }
+
+		// Arrow ->
+		if (input[i] === "-" && input[i + 1] === ">") {
+			tokens.push({ type: "ARROW", value: "->" });
+			i += 2; continue;
+		}
+
+		// Punctuation
+		if (input[i] === "(") { tokens.push({ type: "LPAREN", value: "(" }); i++; continue; }
+		if (input[i] === ")") { tokens.push({ type: "RPAREN", value: ")" }); i++; continue; }
+		if (input[i] === ",") { tokens.push({ type: "COMMA", value: "," }); i++; continue; }
+		if (input[i] === ":") { tokens.push({ type: "COLON", value: ":" }); i++; continue; }
+
+		// Quoted argument
+		if (input[i] === '"' || input[i] === "'") {
+			const quote = input[i];
+			let str = "";
+			i++; // skip opening quote
+			while (i < input.length && input[i] !== quote) {
+				if (input[i] === "\\" && i + 1 < input.length) { i++; str += input[i]; }
+				else { str += input[i]!; }
+				i++;
+			}
+			if (i >= input.length) throw new Error("Unclosed quoted string in chain DSL");
+			i++; // skip closing quote
+			tokens.push({ type: "QUOTED", value: str });
+			continue;
+		}
+
+		// Flag --with-context
+		if (input[i] === "-" && input[i + 1] === "-") {
+			let flag = "";
+			i += 2;
+			while (i < input.length && /[a-zA-Z0-9_-]/.test(input[i]!)) { flag += input[i]; i++; }
+			tokens.push({ type: "FLAG", value: flag });
+			continue;
+		}
+
+		// Number
+		if (/[0-9]/.test(input[i]!)) {
+			let num = "";
+			while (i < input.length && /[0-9]/.test(input[i]!)) { num += input[i]; i++; }
+			tokens.push({ type: "NUMBER", value: num });
+			continue;
+		}
+
+		// Name
+		if (/[a-zA-Z_]/.test(input[i]!)) {
+			let name = "";
+			while (i < input.length && /[a-zA-Z0-9_.-]/.test(input[i]!)) { name += input[i]; i++; }
+			tokens.push({ type: "NAME", value: name });
+			continue;
+		}
+
+		throw new Error(`Unexpected character '${input[i]}' at position ${i} in chain DSL`);
+	}
+
+	return tokens;
+}
+
+// ── Recursive Descent Parser ─────────────────────────────────────────────
+
+class ChainParser {
+	private pos = 0;
+
+	constructor(private tokens: Token[]) {}
+
+	parse(): ChainStep[] {
+		const steps: ChainStep[] = [];
+		steps.push(this.parseStep());
+		while (this.peek("ARROW")) {
+			this.consume("ARROW");
+			steps.push(this.parseStep());
+		}
+		if (this.pos < this.tokens.length) {
+			throw new Error(`Unexpected token '${this.tokens[this.pos]?.value}' at position ${this.pos}`);
+		}
+		return steps;
+	}
+
+	private parseStep(): ChainStep {
+		// Check for parallel(...) construct
+		if (this.peek("NAME", "parallel")) {
+			this.consume("NAME"); // eat "parallel"
+			this.consume("LPAREN");
+			const parallel: ChainStep[] = [];
+			parallel.push(this.parseStep());
+			while (this.peek("COMMA")) {
+				this.consume("COMMA");
+				parallel.push(this.parseStep());
+			}
+			this.consume("RPAREN");
+			const step: ChainStep = { name: "parallel", parallel };
+			this.parseModifiers(step);
+			return step;
+		}
+
+		// Normal step name
+		const name = this.consume("NAME").value;
+		const step: ChainStep = { name };
+
+		// Parse modifiers
+		this.parseModifiers(step);
+		return step;
+	}
+
+	private parseModifiers(step: ChainStep): void {
+		while (this.pos < this.tokens.length) {
+			if (this.peek("COLON")) {
+				this.consume("COLON");
+				const num = this.consume("NUMBER");
+				step.loopCount = Number.parseInt(num.value, 10);
+			} else if (this.peek("FLAG", "with-context")) {
+				this.consume("FLAG");
+				step.withContext = true;
+			} else if (this.peek("QUOTED")) {
+				const arg = this.consume("QUOTED");
+				step.args = step.args ?? [];
+				step.args.push(arg.value);
+			} else {
+				break;
+			}
+		}
+	}
+
+	private peek(type: TokenType, value?: string): boolean {
+		const tok = this.tokens[this.pos];
+		if (!tok) return false;
+		if (tok.type !== type) return false;
+		if (value !== undefined && tok.value !== value) return false;
+		return true;
+	}
+
+	private consume(type: TokenType): Token {
+		const tok = this.tokens[this.pos];
+		if (!tok) throw new Error(`Expected ${type} but reached end of chain DSL`);
+		if (tok.type !== type) throw new Error(`Expected ${type} but got ${tok.type}('${tok.value}')`);
+		this.pos++;
+		return tok;
+	}
+}