Cowork Integration Platform — Starter Repo

Agent-based automation for a global integration team. This is the reference implementation skeleton for the architecture described in docs/.

Shape: agents reason, Ansible mutates, Temporal orchestrates, skills are the unit of change. See docs/agent-automation-implementation.md for the full design.

What's in this repo

docs/                   # Full design docs + vision
skills/                 # Versioned runbooks (mutation, diagnostic, composite)
  duplicate-matching-lines-with-suffix/   (mutation archetype)
  top-process-check/                      (diagnostic archetype)
  guarded-change/                         (composite archetype)
agents/                 # L3 orchestration agents
  incident-responder/   (canonical template)
src/
  control_plane/        # Client + Temporal workflow stubs
  agent_runtime/        # Agent SDK runtime + AuditHooks stub
tests/                  # Skill folder linter + unit tests
scripts/                # bootstrap, validate_skills, run_skill_locally
.vscode/                # Editor config (interpreter, extensions, launch)
.github/workflows/      # CI: skill lint + signature
docker-compose.yml      # Local Temporal + Postgres + MinIO
Makefile                # Common commands
pyproject.toml          # Python deps + tool config

Quick start (10 minutes)

1. Prerequisites

• Python 3.11+
• Docker + Docker Compose
• VSCode with the Python + YAML + Ansible extensions (see .vscode/extensions.json — VSCode will prompt to install them)

2. Bootstrap

./scripts/bootstrap.sh

This creates a virtualenv in .venv/, installs dependencies, and prints next steps. If you prefer to do it by hand:

python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

3. Start the local dev stack

docker compose up -d

This starts:

• Temporal on localhost:7233 (+ Web UI on http://localhost:8233)
• Postgres on localhost:5432 (audit store)
• MinIO on localhost:9000 (S3-compatible blob store for snapshots)

Verify:

make status

4. Lint your skills

make lint-skills

The skill linter validates every folder under skills/:

• SKILL.md present and non-empty
• metadata.yaml parses and matches the schema for its operation_type
• inputs.schema.json is valid JSON Schema
• Mutation skills have apply.yml + rollback.yml + verify.sh
• Diagnostic skills have apply.yml + verify.sh + inverse: null
• Composite skills have compose.yaml + verify.sh + no playbooks

5. Run the test suite

make test

6. Open in VSCode

code .

VSCode will:

• Pick up the .venv/ Python interpreter automatically.
• Prompt to install the recommended extensions.
• Offer launch configurations for:
  • Running the skill linter
  • Running a skill locally via scripts/run_skill_locally.py
  • Starting the Temporal worker (once you wire it up)

How to author a new skill

1. Copy an existing skill folder that matches your archetype:
   • Mutation → copy skills/duplicate-matching-lines-with-suffix/
   • Diagnostic → copy skills/top-process-check/
   • Composite → copy skills/guarded-change/
2. Rename the folder to your skill id.
3. Edit SKILL.md (human intent), metadata.yaml (safety envelope), inputs.schema.json (input contract).
4. Replace apply.yml / rollback.yml / verify.sh with your actual logic.
5. Run make lint-skills — all checks must pass.
6. Add tests under tests/skills/<your_skill_id>/.
7. Open a PR. CI runs the linter + Molecule tests + signs the skill on merge to main.

See docs/agent-automation-implementation.md §3 for the full skill contract and §10 for worked examples.

How to author a new agent

1. Copy agents/incident-responder/.
2. Edit metadata.yaml — set allowed_tools, disallowed_tool_classes, allowed_skill_invocation_types, model pin, reasoning caps.
3. Write system_prompt.md.
4. Implement the tool adapters in tools.py — keep them read-only or plan-producing. Never add shell or file-write tools.
5. Implement the driver workflow in workflow.py.
6. Register the agent with the runtime in src/agent_runtime/registry.py.

See docs/agent-automation-implementation.md §11 for the L3 design.

Safety invariants — these must remain true

This platform is only safe if these hold. Review any PR that might break one with extra scrutiny.

1. Agents cannot mutate. Tool surfaces are declarative; the loader enforces allowed_tools. No agent has shell, file_write, or SSH.
2. Every mutation is reversible. Mutation skills ship rollback.yml; apply.yml snapshots pre-state before any change.
3. Every action is auditable. Every tool call, workflow activity, and mutation writes a hash-chained event to Postgres; snapshots go to S3/MinIO.
4. The system can stop itself. kill_switch_group in skill and agent metadata; Temporal workers honor the paused flag.

Where to start reading the code

In this order:

1. docs/agent-automation-implementation.md — overall architecture.
2. skills/top-process-check/ — simplest complete skill (diagnostic).
3. skills/duplicate-matching-lines-with-suffix/ — mutation with rollback.
4. skills/guarded-change/compose.yaml — composite step graph.
5. agents/incident-responder/ — L3 agent folder.
6. src/control_plane/client.py — the API surface skills and agents call.
7. scripts/validate_skills.py — reference implementation of the skill contract (useful as executable documentation).

Status

This is a starter repo. The intent is: the skills, agents, design, and folder discipline are real and correct; the runtime glue (src/) is scaffolding. Filling in the runtime is Phase 1 of the build plan in docs/agent-automation-implementation.md §7.