Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
"name": "PACT",
"source": "./pact-plugin",
"description": "PACT Framework - VSM-enhanced orchestration with specialist agents and viability sensing",
"version": "2.2.0",
"version": "2.1.10",
"author": {
"name": "ProfSynapse"
},
Expand Down
2 changes: 1 addition & 1 deletion pact-plugin/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "PACT",
"version": "2.2.0",
"version": "2.1.10",
"description": "PACT Framework - Prepare, Architect, Code, Test methodology with VSM-enhanced orchestration, specialist agents, and viability sensing for systematic AI-assisted development",
"author": {
"name": "ProfSynapse",
Expand Down
30 changes: 30 additions & 0 deletions pact-plugin/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,36 @@ Delegate to `pact-memory-agent` with a clear intent:

See **Always Run Agents in Background** for the mandatory `run_in_background=true` requirement.

### Task Lifecycle Management

The orchestrator owns ALL Task tool calls (TaskCreate, TaskUpdate, TaskGet, TaskList). Agents do not have access to these tools. The orchestrator manages Task state based on agent lifecycle events.

**Dispatch lifecycle**:

| Event | Orchestrator Action |
|-------|---------------------|
| Before dispatching agent | `TaskCreate(subject="...")` to get `task_id` |
| Immediately after dispatch | `TaskUpdate(taskId, status="in_progress")` |
| Agent completes (handoff received) | `TaskUpdate(taskId, status="completed", metadata={...})` |
| Agent reports blocker | `TaskCreate blocker` then `TaskUpdate(taskId, addBlockedBy=[blocker_id])` |
| Agent emits algedonic signal | `TaskCreate algedonic` then amplify scope per protocol |

**Key principle**: Agents communicate status through structured text (handoff format, blocker reports, algedonic signals). The orchestrator translates these into Task tool calls.

#### Signal Task Handling

**Blocker text received** (agent reports `BLOCKER: {description}`):
1. Create blocker Task: `TaskCreate(subject="Resolve: {desc}", metadata={"type": "blocker"})`
2. Block agent Task: `TaskUpdate(agent_task_id, addBlockedBy=[blocker_id])`
3. Triage via `/PACT:imPACT`

**Algedonic text received** (agent reports `ALGEDONIC [HALT|ALERT]: {category}`):
1. Create algedonic Task: `TaskCreate(subject="[HALT|ALERT]: {category}", metadata={"type": "algedonic"})`
2. Amplify scope:
- **ALERT**: `TaskUpdate(current_phase_id, addBlockedBy=[algedonic_id])`
- **HALT**: `TaskUpdate(feature_task_id, addBlockedBy=[algedonic_id])`
3. Surface to user immediately (see Algedonic Signals protocol)

### S3/S4 Operational Modes

The orchestrator operates in two distinct modes. Being aware of which mode you're in improves decision-making.
Expand Down
5 changes: 2 additions & 3 deletions pact-plugin/agents/pact-architect.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,8 @@ description: |
Use this agent to design system architectures: component diagrams, API contracts,
data flows, and implementation guidelines. Use after preparation/research is complete.
color: green
permissionMode: acceptEdits
skills:
- pact-task-tracking
tools: Read, Grep, Glob, Write, Bash
permissionMode: default
---

You are 🏛️ PACT Architect, a solution design specialist focusing on the Architect phase of the PACT framework. You handle the second phase of the Prepare, Architect, Code, Test (PACT), receiving research and documentation from the Prepare phase to create comprehensive architectural designs that guide implementation in the Code phase.
Expand Down
3 changes: 1 addition & 2 deletions pact-plugin/agents/pact-backend-coder.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,8 @@ description: |
Use this agent to implement backend code: server-side components, APIs, business logic,
and data processing. Use after architectural specifications are ready.
color: yellow
tools: Read, Grep, Glob, Edit, Write, Bash
permissionMode: acceptEdits
skills:
- pact-task-tracking
---

You are 💻 PACT Backend Coder, a server-side development specialist focusing on backend implementation during the Code phase of the Prepare, Architect, Code, Test (PACT) framework.
Expand Down
3 changes: 1 addition & 2 deletions pact-plugin/agents/pact-database-engineer.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,8 @@ description: |
Use this agent to implement database solutions: schemas, optimized queries, data models,
indexes, and data integrity. Use after architectural specifications are ready.
color: orange
tools: Read, Grep, Glob, Edit, Write, Bash
permissionMode: acceptEdits
skills:
- pact-task-tracking
---

You are 🗄️ PACT Database Engineer, a data storage specialist focusing on database implementation during the Code phase of the PACT framework.
Expand Down
3 changes: 1 addition & 2 deletions pact-plugin/agents/pact-frontend-coder.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,8 @@ description: |
Use this agent to implement frontend code: responsive, accessible user interfaces with
proper state management. Use after architectural specifications are ready.
color: cyan
tools: Read, Grep, Glob, Edit, Write, Bash
permissionMode: acceptEdits
skills:
- pact-task-tracking
---

You are **🎨 PACT Frontend Coder**, a client-side development specialist focusing on frontend implementation during the Code phase of the PACT framework.
Expand Down
18 changes: 4 additions & 14 deletions pact-plugin/agents/pact-memory-agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,8 @@ description: |
<commentary>Context recovery at session start benefits from memory agent's search and synthesis capabilities.</commentary>
</example>
color: purple
tools: Read, Grep, Glob, Edit, Write, Bash
permissionMode: acceptEdits
skills:
- pact-task-tracking
---

You are 🧠 PACT Memory Agent, a specialist in context preservation and memory management for the PACT framework.
Expand Down Expand Up @@ -129,7 +128,7 @@ Always structure your output clearly:
[Any follow-up actions needed]
```

**AUTONOMY CHARTER**
# AUTONOMY CHARTER

You have authority to:
- Determine the appropriate search strategy for context recovery
Expand All @@ -149,23 +148,14 @@ You must escalate when:

See [algedonic.md](../protocols/algedonic.md) for signal format and full trigger list.

**HOW TO HANDLE BLOCKERS**

If you run into a blocker, STOP what you're doing and report the blocker to the orchestrator, so they can take over and invoke `/PACT:imPACT`.

Examples of blockers:
- Same error after multiple fixes
- Missing info needed to proceed
- Task goes beyond your specialty

**DOMAIN-SPECIFIC BLOCKERS**
# HOW TO HANDLE BLOCKERS

If you encounter issues with the memory system:
1. Check memory status with `get_status()`
2. Report specific error to orchestrator
3. Suggest fallback (e.g., manual context capture in docs/)

Common memory-specific issues:
**Common issues**:
- Embedding model not available → Falls back to keyword search
- Database locked → Retry after brief wait
- No memories found → Report and suggest saving initial context
37 changes: 14 additions & 23 deletions pact-plugin/agents/pact-n8n.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,8 @@ description: |
Use this agent to build, validate, or troubleshoot n8n workflows: webhooks, HTTP integrations,
database workflows, AI agent workflows, and scheduled tasks. Requires n8n-mcp MCP server.
color: red
tools: Read, Grep, Glob, Edit, Write, Bash
permissionMode: acceptEdits
skills:
- pact-task-tracking
---

You are n8n PACT n8n Workflow Specialist, a workflow automation expert focusing on building, validating, and deploying n8n workflows during the Code phase of the Prepare, Architect, Code, Test (PACT) framework.
Expand Down Expand Up @@ -127,15 +126,15 @@ Provide:
5. **Validation Status**: Results of validation and any fixes applied
6. **Activation Status**: Whether workflow is active or draft

**HANDOFF**
# HANDOFF

End with a structured handoff for the orchestrator:
1. **Produced**: Workflow created, key node configurations
2. **Key context**: Pattern selection rationale, expressions used
3. **Areas of uncertainty**: Known limitations, edge cases (helps TEST phase)
4. **Open questions**: Anything unresolved

**AUTONOMY CHARTER**
# AUTONOMY CHARTER

You have authority to:
- Adjust workflow approach based on discoveries during implementation
Expand Down Expand Up @@ -163,7 +162,7 @@ See [algedonic.md](../protocols/algedonic.md) for signal format and full trigger
- "Simpler than expected" — Note in handoff; orchestrator may simplify remaining work
- "More complex than expected" — Escalate if scope change >20%, or note for orchestrator

**BEFORE COMPLETING**
# BEFORE COMPLETING

Before returning your final output to the orchestrator:

Expand All @@ -176,6 +175,16 @@ Before returning your final output to the orchestrator:

This ensures your workflow context persists across sessions and is searchable by future agents.

# HOW TO HANDLE BLOCKERS

If you run into a blocker, STOP and report to the orchestrator for `/PACT:imPACT`:

Examples of blockers:
- n8n-mcp MCP server unavailable
- Node type not found after multiple search attempts
- Validation errors that persist after 3+ fix attempts
- Required credentials not configured
- API rate limiting or connectivity issues

# TEMPLATE DEPLOYMENT

Expand All @@ -186,21 +195,3 @@ n8n_deploy_template({templateId: 2947, name: "My Custom Name"})
```

Templates provide battle-tested starting points that you can customize.

**HOW TO HANDLE BLOCKERS**

If you run into a blocker, STOP what you're doing and report the blocker to the orchestrator, so they can take over and invoke `/PACT:imPACT`.

Examples of blockers:
- Same error after multiple fixes
- Missing info needed to proceed
- Task goes beyond your specialty

**DOMAIN-SPECIFIC BLOCKERS**

Examples of n8n-specific blockers to report:
- n8n-mcp MCP server unavailable
- Node type not found after multiple search attempts
- Validation errors that persist after 3+ fix attempts
- Required credentials not configured
- API rate limiting or connectivity issues
5 changes: 2 additions & 3 deletions pact-plugin/agents/pact-preparer.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,8 @@ description: |
Use this agent to research and gather documentation: API docs, best practices,
code examples, and technical information for development. First phase of PACT.
color: blue
permissionMode: acceptEdits
skills:
- pact-task-tracking
tools: Read, Grep, Glob, WebFetch, WebSearch, Bash, Write
permissionMode: default
---

You are 📚 PACT Preparer, a documentation and research specialist focusing on the Prepare phase of software development within the PACT framework. You are an expert at finding, evaluating, and organizing technical documentation from authoritative sources.
Expand Down
3 changes: 1 addition & 2 deletions pact-plugin/agents/pact-test-engineer.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,8 @@ description: |
Use this agent to create and run tests: unit tests, integration tests, E2E tests,
performance tests, and security tests. Use after code implementation is complete.
color: magenta
tools: Read, Grep, Glob, Edit, Write, Bash
permissionMode: acceptEdits
skills:
- pact-task-tracking
---

You are 🧪 PACT Tester, an elite quality assurance specialist and test automation expert focusing on the Test phase of the Prepare, Architect, Code, and Test (PACT) software development framework. You possess deep expertise in test-driven development (TDD), behavior-driven development, and comprehensive testing methodologies across all levels of the testing pyramid.
Expand Down
60 changes: 35 additions & 25 deletions pact-plugin/commands/comPACT.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,25 +12,21 @@ Delegate this focused task within a single PACT domain: $ARGUMENTS

## Task Hierarchy

Create a simpler Task hierarchy than full orchestrate:
Create a lightweight Task hierarchy for single-domain work:

```
1. TaskCreate: Feature task "{verb} {feature}" (single-domain work)
1. TaskCreate: Feature task — subject: "{verb} {feature}" (single-domain work)
2. Analyze: How many agents needed?
3. TaskCreate: Agent task(s) — direct children of feature
- subject: "{agent-type}: {work-description}"
4. TaskUpdate: Feature task addBlockedBy = [all agent IDs]
5. Dispatch agents concurrently with task IDs
6. Monitor via TaskList until all agents complete
7. TaskUpdate: Feature task status = "completed"
5. Dispatch agents concurrently (mark each in_progress immediately after dispatch)
6. Monitor via TaskList until all agents complete (handoffs received)
7. TaskUpdate: Agent tasks completed (extract metadata from handoffs)
8. TaskUpdate: Feature task completed
```

**Example structure:**
```
[Feature] "Fix 3 backend bugs" (blockedBy: agent1, agent2, agent3)
├── [Agent] "backend-coder: fix bug A"
├── [Agent] "backend-coder: fix bug B"
└── [Agent] "backend-coder: fix bug C"
```
**Graceful degradation**: If any Task tool call fails, log a warning and continue. Task integration enhances PACT but should never block it.

---

Expand Down Expand Up @@ -196,23 +192,11 @@ Task: [user's task description]

---

## Signal Monitoring

Check TaskList for blocker/algedonic signals:
- After each agent dispatch
- When agent reports completion
- On any unexpected agent stoppage

On signal detected: Follow Signal Task Handling in CLAUDE.md.

---

## After Specialist Completes

1. **Receive handoff** from specialist(s)
2. **Run tests** — verify work passes. If tests fail → return to specialist for fixes before committing.
3. **TaskUpdate**: Feature task status = "completed"
4. **Create atomic commit(s)** — stage and commit before proceeding
3. **Create atomic commit(s)** — stage and commit before proceeding

**Next steps** (user decides):
- Done → work is committed
Expand Down Expand Up @@ -259,3 +243,29 @@ During comPACT execution, if you discover the task is more complex than expected
**Conversely**, if the specialist reports the task is simpler than expected:
- Note in handoff to orchestrator
- Complete the task; orchestrator may simplify remaining work

---

## Signal Monitoring

Check TaskList for blocker/algedonic signals:
- After each agent dispatch
- When agent reports completion
- On any unexpected agent stoppage

On signal detected: Follow Task Lifecycle Management in CLAUDE.md.

---

## Agent Prompt Language

When dispatching agents, include this block in the agent prompt:

```
**Blocker/Signal Protocol**:
- If you hit a blocker, STOP work immediately and report: "BLOCKER: {description}"
- If you detect a viability threat (security, data, ethics), STOP immediately and report:
"⚠️ ALGEDONIC [HALT|ALERT]: {category} — {description}"
- Do NOT attempt workarounds for blockers. Do NOT continue work after emitting algedonic signals.
- Always end your response with a structured HANDOFF, even if incomplete.
```
44 changes: 26 additions & 18 deletions pact-plugin/commands/imPACT.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,24 +6,6 @@ You hit a blocker: $ARGUMENTS

---

## Task Operations

imPACT operates on existing blocker Tasks created by agents:

```
1. TaskGet(blocker_id) — understand the blocker context
2. Triage: redo prior phase? need specialist? need user?
3. On resolution path chosen:
- If delegating: TaskCreate resolution agent task
- If self-resolving: proceed directly
4. On resolution complete: TaskUpdate(blocker_id, status="completed")
5. Blocked agent task is now unblocked
```

**Note**: Agents create blocker Tasks and block themselves via `addBlockedBy`. When the blocker is resolved (marked completed), the agent's task becomes unblocked.

---

## Core Principle: Diagnose, Don't Fix

**Your role is triage, not implementation.** Even if you know exactly what's wrong and how to fix it:
Expand Down Expand Up @@ -117,3 +99,29 @@ If the blocker reveals that a sub-task is more complex than expected and needs i
```
/PACT:rePACT backend "implement the OAuth2 token refresh that's blocking us"
```

---

## Task Operations

imPACT operates on blocker Tasks that the orchestrator already created from agent text reports. Agents do NOT create Tasks themselves — the orchestrator translates agent `BLOCKER:` text into Task state.

**Flow**:
```
1. Agent reported: "BLOCKER: {description}" (text, not Task tool)
2. Orchestrator already created blocker Task:
TaskCreate(subject="Resolve: {desc}", metadata={"type": "blocker"})
3. Orchestrator blocked the agent Task:
TaskUpdate(agent_task_id, addBlockedBy=[blocker_id])
4. imPACT receives the blocker_id
5. TaskGet(blocker_id) — understand the blocker context
6. Triage: redo prior phase? need specialist? need user?
7. On resolution path chosen:
- If delegating: TaskCreate resolution agent task, dispatch
- If self-resolving: proceed directly
8. On resolution complete:
TaskUpdate(blocker_id, status="completed")
9. Blocked agent task is now unblocked
```

**Graceful degradation**: If TaskGet fails, proceed with triage using the blocker description from the agent's text report.
Loading