Portable Agent Kit

Portable Agent Collaboration Kit (PACK)

A zero-dependency framework for multi-agent AI collaboration and strategic project alignment.

---

Why This Kit?

Modern AI-assisted development involving multiple agents (planners, coders, reviewers, auditors) requires more than just code; it requires strategic orchestration. Without clear coordination:

• Agents overwrite each other's work
• Context "drifts" from the original requirements
• Handoffs are unclear and messy
• Environmental friction (Node versions, script paths) blocks progress

PACK solves these problems with a dual-layer framework: an Operational Layer (.agent/) for day-to-day work, and a Strategic Layer (.pde/) for maintaining project integrity.

---

Features

---

Quick Start

1. Install & Deploy

python3 deploy_agent_kit.py --dest /path/to/your/repo

2. Unified Initialization

For a fresh repository, run the all-in-one setup:

./.agent/tools/bin/pack-init.sh

3. Start Collaborating

1. Set your project name: export PROJECT_NAME="my-project"
2. Edit .agent/AGENTS.md to define your agent roles.

---

The Dual-Layer Architecture

Layer 1: Operational (.agent/)

The Operational Layer handles asynchronous coordination between agents.

• AGENTS.md: Roster of roles (Builder, Planner, Auditor).
• HANDOFF.md: Current state of the active session.
• skills/: Reusable workflows (e.g., gemini-audit).

Layer 2: Strategic (.pde/)

The PACK Development Engine (PDE) provides structural maintenance for the kit itself.

• MANIFEST.md: The project's North Star and quarterly objectives.
• friction_log.md: Tracking and resolving workflow pain points.
• roadmap.md: Strategic evolution of the collaboration model.

---

What's Included

.
+-- .agent/                       # Operational coordination
|   +-- AGENTS.md                 # Agent roster and rules
|   +-- skills/                   # Repeatable workflows
|   +-- ai/                       # Persona profiles & protocols
|   +-- tools/
|       +-- bin/
|           +-- pack-init.sh      # Unified setup script
|           +-- audit_task.sh     # Headless auditor
+-- .pde/                         # Strategic alignment (maintainers)
|   +-- MANIFEST.md               # The North Star
|   +-- state/                    # friction_log, roadmap
+-- deploy_agent_kit.py           # Installer script
+-- lmstudio_mcp.py               # Generated by setup_offline_ai.py (not in repo)
+-- templates/
|   +-- parallel-cloud-tasks-kit/ # Portable cloud task batch workflow
|   +-- iterative-dev-protocol.md # Orchestrated batch-iterate-merge cycle
|   +-- prompt-attribution-protocol.md # Prompt origin tracking template

---

Templates

Reusable add-ons you can copy into any repo:

• templates/parallel-cloud-tasks-kit/ — generate 5 disjoint cloud tasks, review, and merge them safely.
  • See templates/parallel-cloud-tasks-kit/README.md for full instructions.
• templates/iterative-dev-protocol.md — orchestrated Generate/Execute/Merge/Archive cycle for continuous parallel batch development. Wraps the parallel cloud tasks pattern into a repeatable state machine.
• templates/prompt-attribution-protocol.md — reusable template for adding the Prompt Attribution & Clarification Protocol to any repo's agent instructions file.

Parallel Cloud Tasks — Quick Use

# From this repo, copy the kit into your target repo
cp -R templates/parallel-cloud-tasks-kit /path/to/your/repo/

# In the target repo, open SCANNER_PROMPT.md and edit the CONFIG block:
# - PROJECT_NAME, SOURCE_DIRS, TEST_COMMAND, BASE_BRANCH, etc.

Run the workflow (in the target repo):

1. Paste SCANNER_PROMPT.md into Local Claude Code to generate cloud_tasks/
2. Open 5 Cloud sessions and paste cloud_tasks/task_N.md into each
3. Paste MERGE_PROTOCOL.md into Local Claude Code to review/merge

Compatibility:

• Requires a git repo
• Merge protocol assumes GitHub + gh CLI (adjust if using another host)

Iterative Dev Protocol — Quick Use

The iterative protocol adds a repeatable cycle on top of parallel cloud tasks:

1. Generate — scan for the next batch of disjoint tasks
2. Execute — spawn parallel cloud sessions
3. Merge — review, test, and squash-merge each PR
4. Archive — preserve batch history and loop

# Copy the template into your orchestrator session
cat templates/iterative-dev-protocol.md
# Fill in the variables: ${ProjectName}, ${BatchSize}, ${TestCommand}, ${TaskPriority}
# Paste into your orchestrating agent to start the cycle

The protocol includes a state machine for resuming mid-cycle and guardrails for task isolation.

---

Usage Highlights

Recording a Handoff

python3 .agent/tools/utilities/update_agent_conversation_log.py \
  --agent builder \
  --summary "Implemented login feature" \
  --handoff reviewer

Context-Aware Offline AI

If using LM Studio, the lmstudio_mcp.py bridge includes a get_pack_context tool, allowing local models to "reach into" the .agent folder to read the current task and handoff state automatically.

---

Requirements

• Python 3.8+ (uses only standard library)
• Node.js v20+ (required for Gemini CLI integration)
• Any AI Model: Claude, GPT, Gemini, Codex, or local LLMs

---

License

MIT License - see LICENSE details.

---

Stop losing context. Start collaborating.