gentle-agent-extensions 0.0.0-stage → 1.0.1

package/.manifest.json

@@ -0,0 +1,15 @@
+{
+  "version": "1.0",
+  "description": "Manifest of files managed by gentle-agent-extensions. Used by sync.sh to verify ownership and prevent modification of external files.",
+  "managedPaths": {
+    "extensions": [],
+    "agents": [],
+    "routing": [],
+    "overlays": [],
+    "skills": [],
+    "mcp": [],
+    "scripts": [],
+    "assets": []
+  },
+  "installProfiles": {}
+}

package/README.md

@@ -1,3 +1,420 @@
-# Temporary Holding Version
+# gentle-agent-extensions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Extend Gentle AI and Gentle Pi with custom agents, overlays, routing rules, and skills — declaratively, without modifying the official repositories.
+
+## What This Project Does
+
+- **Adds custom agents** to Gentle Pi via declarative Markdown definitions
+- **Applies instruction overlays** to existing agents or the orchestrator without modifying their original definitions
+- **Defines routing rules** so the orchestrator knows when to delegate to custom agents
+- **Provides project skills** that teach future agents how to extend this system correctly
+- **Installs as a Pi extension** using the official extension mechanism
+- **Syncs idempotently** — repeated runs with the same configuration produce no changes
+
+## What This Project Does NOT Do
+
+- ❌ Modify Gentle AI or Gentle Pi official repositories
+- ❌ Create parallel agent registries or skill indexes
+- ❌ Require code changes for new agents/overlays
+- ❌ Install demo agents or overlays by default
+- ❌ Automatically update Gentle AI or Gentle Pi
+
+## Architecture
+
+```
+gentle-agent-extensions/
+├── agents/              # Custom agent definitions (Markdown + YAML frontmatter)
+├── overlays/            # Instruction overlays for existing agents/orchestrator
+├── routing/             # Delegation rules for custom agents
+├── skills/              # Project skills (including gentle-agent-extension skill)
+├── extensions/          # Pi extension (gentle-agent-extensions.ts)
+├── scripts/             # install.sh, sync.sh, doctor.sh
+├── tests/               # Automated tests
+├── docs/                # Documentation (conventions.md)
+├── .manifest.json       # Tracks project-owned files
+└── README.md            # This file
+```
+
+### Extension (`extensions/gentle-agent-extensions.ts`)
+
+A Pi extension that:
+1. **Discovers** agents, overlays, and skills from project directories on `session_start`
+2. **Injects** orchestrator context via `before_agent_start` using `appendSystemPromptOnce`
+3. **Applies overlays** to target agents/orchestrator at runtime
+4. **Registers commands**: `/gentle-extensions:sync`, `/gentle-extensions:doctor`, `/gentle-extensions:status`
+
+### Declarative Conventions
+
+See [docs/conventions.md](docs/conventions.md) for complete specification.
+
+**Agents** (`agents/{name}.md`):
+```markdown
+---
+name: my-agent
+description: "When to use this agent"
+model: anthropic/claude-opus-4
+thinking: high
+mode: task
+tools: [read, write, bash]
+---
+# Agent Instructions
+...
+```
+
+**Overlays** (`overlays/{target}.overlay.md`):
+```markdown
+---
+target: orchestrator        # or agent name
+priority: 100
+mode: append
+---
+# Additional instructions appended to target's prompt
+```
+
+**Routing** (`routing/{agent}.md`):
+```markdown
+---
+agent: my-agent
+triggers: ["trigger phrase"]
+conditions: ["condition"]
+delegation: subagent_run
+---
+```
+
+**Skills** (`skills/{name}/SKILL.md`):
+Follows [Gentle AI Skill Style Guide](https://github.com/Gentleman-Programming/gentle-pi/blob/main/docs/skill-style-guide.md)
+
+## Installation
+
+### Prerequisites
+
+- Pi 1.2.0+
+- Gentle Pi (`gentle-pi` package installed)
+- Node.js 22+
+
+### Quick Install
+
+```bash
+# Clone or navigate to the project
+cd gentle-agent-extensions
+
+# Make scripts executable
+chmod +x scripts/*.sh
+
+# Install for standard Pi (default profile)
+./scripts/install.sh
+
+# Or for Gentle Shell isolated
+./scripts/install.sh --profile gentle-shell
+
+# Or for Gentle Shell with --link
+./scripts/install.sh --profile gentle-shell-linked
+```
+
+### Manual Installation Steps
+
+1. **Register extension with Pi**:
+   ```bash
+   pi install file:$(pwd)
+   ```
+
+2. **Sync project agents/overlays**:
+   ```bash
+   ./scripts/sync.sh
+   ```
+
+3. **Verify installation**:
+   ```bash
+   ./scripts/doctor.sh
+   ```
+
+4. **Start Pi and check status**:
+   ```
+   /gentle-extensions:status
+   ```
+
+### Installation Profiles
+
+| Profile | Agent Home | Use Case |
+|---------|------------|----------|
+| `pi` | `~/.pi/agent` | Standard Pi installation |
+| `gentle-shell` | `~/.local/share/gentle-shell/agent` | Isolated Gentle Shell |
+| `gentle-shell-linked` | `~/.pi/agent` | Gentle Shell with `--link` |
+
+Use `--agent-home PATH` to override the profile default.
+
+### Dry Run
+
+Preview changes without making them:
+```bash
+./scripts/install.sh --dry-run
+./scripts/sync.sh --dry-run
+```
+
+## Usage
+
+### Synchronization
+
+After adding/modifying agents, overlays, routing, or skills:
+```bash
+./scripts/sync.sh
+```
+
+Options:
+- `--dry-run` — Preview changes
+- `--check` — Validate only (exit 1 on issues)
+- `--profile PROFILE` / `--agent-home PATH` — Target installation
+
+### Doctor
+
+Check installation health:
+```bash
+./scripts/doctor.sh
+./scripts/doctor.sh --verbose  # Detailed output
+```
+
+Checks:
+- Project structure completeness
+- Manifest validity
+- Extension installation
+- Pi / Gentle Pi versions
+- Agent/overlay/skill validation
+- Conflict detection (shadowing, unknown targets)
+- Skill registry status
+- Script permissions
+
+### Status Command
+
+Inside Pi:
+```
+/gentle-extensions:status
+```
+
+Shows discovered agents, overlays, skills directory status.
+
+## Adding a New Agent
+
+Follow **Procedure A** from the `gentle-agent-extension` skill:
+
+```bash
+# 1. Create agent definition
+cat > agents/my-agent.md <<'EOF'
+---
+name: my-agent
+description: "Reviews code for security issues"
+model: anthropic/claude-opus-4
+thinking: high
+mode: task
+tools: [read, grep, bash]
+---
+# My Agent
+
+You are a security reviewer...
+EOF
+
+# 2. Create routing (if semantic delegation needed)
+cat > routing/my-agent.md <<'EOF'
+---
+agent: my-agent
+triggers:
+  - "security review"
+  - "check for vulnerabilities"
+conditions:
+  - "User requests security review"
+delegation: subagent_run
+---
+# Routing for my-agent
+...
+EOF
+
+# 3. Create skill (for semantic activation)
+mkdir -p skills/my-agent
+cat > skills/my-agent/SKILL.md <<'EOF'
+---
+name: my-agent
+description: "Trigger: security review, check vulnerabilities. Delegates to my-agent for security reviews."
+license: Apache-2.0
+metadata:
+  author: your-name
+  version: "1.0"
+---
+# My Agent Skill
+## Activation Contract
+Use when user requests security review.
+## Hard Rules
+Only delegate via subagent_run to my-agent.
+## Decision Gates
+| Situation | Action |
+|-----------|--------|
+| "security review" | Delegate to my-agent |
+| General coding | Do NOT delegate |
+## Execution Steps
+1. Identify files to review
+2. Call subagent_run with agent=my-agent
+3. Return results
+## Output Contract
+Security findings with severity
+## References
+- agents/my-agent.md
+- routing/my-agent.md
+EOF
+
+# 4. Sync and verify
+./scripts/sync.sh
+./scripts/doctor.sh
+```
+
+Test in Pi:
+```
+"Please do a security review of my changes"
+```
+
+### Adding an Overlay
+
+Follow **Procedure B** from the skill:
+
+```bash
+# 1. Create overlay for existing agent or orchestrator
+cat > overlays/gentle-ai-worker.overlay.md <<'EOF'
+---
+target: gentle-ai-worker
+priority: 100
+mode: append
+---
+# Overlay for gentle-ai-worker
+
+## Additional Instructions
+
+When writing tests, always use table-driven tests.
+Prefer the project's test utilities.
+EOF
+
+# 2. Sync and verify
+./scripts/sync.sh
+./scripts/doctor.sh
+```
+
+The overlay instructions are appended to the target agent's prompt at runtime via `before_agent_start`.
+
+## Verifying Routing and Activation
+
+1. **Check status**: `/gentle-extensions:status`
+2. **Trigger delegation**: Use trigger phrases from routing
+3. **Check doctor**: `./scripts/doctor.sh` validates targets exist
+4. **Inspect prompt**: Add temporary overlay with obvious marker to verify injection
+
+## Troubleshooting
+
+### Agent Not Discovered
+
+```bash
+./scripts/doctor.sh --verbose
+# Check:
+# - Agent file in agents/ with .md extension
+# - Valid frontmatter with name field
+# - sync.sh ran successfully
+# - Extension loaded (check Pi startup logs)
+```
+
+### Overlay Not Applied
+
+```bash
+./scripts/doctor.sh
+# Check:
+# - Overlay file in overlays/ with .overlay.md extension
+# - Target exists (global agent, project agent, or "orchestrator")
+# - Extension's before_agent_start handler running
+```
+
+### Skill Not Indexed
+
+```bash
+# Refresh skill registry
+/skill-registry:refresh
+
+# Verify
+cat .atl/skill-registry.md | grep your-skill
+```
+
+### Extension Not Loading
+
+```bash
+# Check Pi settings
+cat ~/.pi/agent/settings.json
+# Should include: { "packages": [{ "source": "file:/path/to/gentle-agent-extensions" }] }
+
+# Reinstall
+pi remove file:/path/to/gentle-agent-extensions
+pi install file:/path/to/gentle-agent-extensions
+```
+
+### Conflicts Detected
+
+Doctor reports:
+- **Shadowing**: Project agent same name as global agent → rename or accept
+- **Unknown overlay target**: Target agent doesn't exist → create agent or fix target name
+
+## Limitations
+
+| Limitation | Workaround |
+|------------|------------|
+| No agent removal via sync | Manually delete from `.pi/agents/` and manifest |
+| Overlay priority only affects order | Use single overlay per target, or order by priority |
+| Skills require manual registry refresh | Run `/skill-registry:refresh` after adding skills |
+| No hot-reload of extension | Restart Pi or `reload` command |
+| Profile detection is manual | Use `--profile` or `--agent-home` explicitly |
+
+## Development
+
+### Running Tests
+
+```bash
+node --test tests/gentle-extensions.test.ts
+```
+
+### Project Skill
+
+The `gentle-agent-extension` skill teaches agents how to extend this system:
+```
+skills/gentle-agent-extension/SKILL.md
+```
+
+Load it when working on this project:
+```
+/skill-registry:refresh
+# Then in agent context, the skill will be available for relevant tasks
+```
+
+### Extending the Extension
+
+Changes to `extensions/gentle-agent-extensions.ts` are exceptional. Before modifying:
+1. Verify the declarative approach cannot achieve the goal
+2. Document the architectural justification
+3. Update tests and conventions.md
+
+## Compatibility
+
+Tested with:
+- Pi 1.4.0+
+- gentle-pi (bundled in Gentle Shell)
+- gentle-ai (bundled)
+
+Version detection via `doctor.sh`.
+
+## License
+
+Apache-2.0 — see LICENSE file.
+
+## References
+
+- [Gentle Pi Documentation](https://github.com/Gentleman-Programming/gentle-shell)
+- [Gentle AI Skill Style Guide](https://github.com/Gentleman-Programming/gentle-pi/blob/main/docs/skill-style-guide.md)
+- [Pi Extensions API](https://pi.dev/docs/latest/extensions)
+- [Pi Packages](https://pi.dev/docs/latest/packages)
+---
+
+<div align="center">
+
+![Built with Gentle-AI](https://img.shields.io/badge/Built%20with-Gentle--AI-F095C8?style=for-the-badge&labelColor=1A1218)
+
+</div>

package/docs/conventions.md

@@ -0,0 +1,278 @@
+# Declarative Conventions for gentle-agent-extensions
+
+This document defines the file structure and conventions for extending Gentle AI and Gentle Pi through this project.
+
+## Directory Structure
+
+```
+gentle-agent-extensions/
+├── agents/              # Custom agent definitions (Markdown with YAML frontmatter)
+├── routing/             # Routing instructions for custom agents
+├── overlays/            # Instruction overlays for orchestrator and existing agents
+├── skills/              # Project skills for agent programming
+├── mcp/                 # MCP server definitions (JSON)
+├── scripts/             # Installation and synchronization scripts
+├── tests/               # Automated tests
+├── assets/              # Templates, schemas, examples
+├── docs/                # Documentation
+└── .manifest.json       # Track project-owned files
+```
+
+## 1. Agent Definitions (`agents/`)
+
+Custom agents follow Gentle Pi's native agent format: Markdown files with YAML frontmatter.
+
+### File Naming
+
+```
+agents/{agent-name}.md
+```
+
+### Frontmatter Schema
+
+```yaml
+---
+name: {agent-name}
+description: "One-line description of when this agent should be used"
+model: {provider/model}          # optional, e.g. "anthropic/claude-opus-4"
+thinking: {minimal|low|medium|high}  # optional
+mode: {task|background}           # optional, default: task
+tools: [tool1, tool2, ...]        # optional, defaults to Pi defaults
+---
+```
+
+### Body
+
+The body contains the agent's instructions/prompt. This follows the same format as Gentle AI's agent definitions.
+
+### Discovery
+
+Agents are discovered by Gentle Pi from:
+- Global: `~/.pi/agent/agents/`, `~/.pi/agent/subagents/`
+- Project: `<cwd>/.pi/agents/`, `<cwd>/.pi/subagents/`
+
+This project's `sync.sh` will symlink or copy agents from `agents/` to the appropriate project directory.
+
+## 2. Routing Instructions (`routing/`)
+
+Routing instructions tell the orchestrator when to delegate to a custom agent.
+
+### File Naming
+
+```
+routing/{agent-name}.md
+```
+
+### Format
+
+```markdown
+---
+agent: {agent-name}
+triggers:
+  - "trigger phrase 1"
+  - "trigger phrase 2"
+conditions:
+  - "condition description"
+delegation: subagent_run
+---
+
+# Routing Instructions for {agent-name}
+
+## When to Use
+
+[Description of when this agent should be delegated to]
+
+## How to Delegate
+
+Use the `subagent_run` tool with:
+- `agent`: "{agent-name}"
+- `task`: "[specific task description]"
+- `label`: "[3-6 word label]"
+- `mode`: "task" | "background"
+```
+
+### Skill Integration
+
+Each agent that needs semantic routing should have an associated skill in `skills/` with an explicit Activation Contract.
+
+## 3. Overlays (`overlays/`)
+
+Overlays add instructions to existing agents or the orchestrator without modifying their original definitions.
+
+### File Naming
+
+```
+overlays/{target-name}.overlay.md
+```
+
+Where `{target-name}` is either:
+- An agent name (e.g., `gentle-ai-worker.overlay.md`)
+- `orchestrator` for orchestrator-level overlays
+
+### Format
+
+```markdown
+---
+target: {agent-name|orchestrator}
+priority: 100              # optional, higher = applied later
+mode: append               # currently only 'append' is supported
+---
+
+# Overlay for {target-name}
+
+## Additional Instructions
+
+[Instructions to append to the target's prompt]
+```
+
+### Application Mechanism
+
+Overlays are applied via the `before_agent_start` event by mutating `systemPromptOptions.appendSystemPrompt`. This follows Gentle Pi's established pattern (see `lib/append-system-prompt.ts`).
+
+## 4. Skills (`skills/`)
+
+Skills follow the Gentle AI skill format with required sections:
+
+```
+skills/{skill-name}/
+├── SKILL.md
+├── assets/       # optional
+└── references/   # optional
+```
+
+### Required SKILL.md Sections
+
+1. **Activation Contract** - When to use this skill
+2. **Hard Rules** - Constraints and restrictions
+3. **Decision Gates** - Decision tables for choices
+4. **Execution Steps** - Step-by-step procedures
+5. **Output Contract** - What the agent should produce
+6. **References** - Local file paths
+
+## 5. Installation Profiles
+
+The project supports multiple installation targets:
+
+| Profile | Agent Home | Use Case |
+|---------|------------|----------|
+| `pi` | `~/.pi/agent` | Standard Pi installation |
+| `gentle-shell` | `~/.local/share/gentle-shell/agent` | Isolated Gentle Shell |
+| `gentle-shell-linked` | `~/.pi/agent` | Gentle Shell with `--link` |
+
+## 6. Sync Behavior
+
+`sync.sh` performs:
+1. Detect declared features (agents, routing, overlays, skills, mcp)
+2. Validate metadata and files
+3. Resolve native agent/skill paths for the target profile
+4. Install/update only project-owned files
+5. Update skill registry via official mechanism
+6. Prepare orchestrator routing context
+7. Validate overlays, detect conflicts
+8. Update manifest
+9. Report issues requiring intervention
+
+Idempotent: repeated runs with same config produce no changes.
+
+## 7. MCP Server Definitions (`mcp/`)
+
+MCP servers are defined as JSON files in the `mcp/` directory. Each file defines one server.
+
+### File Naming
+
+```
+mcp/{server-name}.mcp.json
+```
+
+### Schema
+
+```json
+{
+  "name": "server-name",
+  "description": "What this server provides",
+  "transport": "stdio|http",
+  "command": "npx",
+  "args": ["-y", "@pkg/server"],
+  "url": "https://example.com/mcp",
+  "env": {"KEY": "${ENV_VAR}"},
+  "exposure": "codemode",
+  "toolExposure": {},
+  "enabled": true,
+  "timeout": 60,
+  "install": {
+    "package": "@pkg/server",
+    "version": "1.0.0",
+    "manager": "npx"
+  },
+  "auth": {
+    "type": "oauth|bearer|none",
+    "envVar": "TOKEN_ENV_VAR",
+    "description": "OAuth flow or bearer token"
+  },
+  "capabilities": ["tools", "resources"],
+  "agentDependencies": ["agent-name"]
+}
+```
+
+### Field Descriptions
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique identifier (letters, digits, `_`, `-` only) |
+| `description` | Yes | One-line description for system prompt |
+| `transport` | Yes | `stdio` or `http` (streamable HTTP) |
+| `command` | stdio only | Executable (not shell command) |
+| `args` | stdio only | Array of arguments |
+| `url` | http only | Server URL |
+| `env` | No | Environment variables; use `${VAR}` for substitution |
+| `exposure` | No | Tool exposure: `codemode` (default), `direct`, `deferred`, `hidden` |
+| `toolExposure` | No | Per-tool exposure overrides |
+| `enabled` | No | Default `true`; `false` keeps entry without connecting |
+| `timeout` | No | Per-request timeout in seconds (default 60) |
+| `install` | No | Installation metadata for optional auto-install |
+| `auth` | No | Authentication requirements (no secrets in repo) |
+| `capabilities` | No | Declared: `tools`, `resources` |
+| `agentDependencies` | No | List of agent names that need this server |
+
+### Discovery
+
+The extension discovers `*.mcp.json` files in `mcp/` on `session_start` and registers them via `pi.registerMcpServer()`.
+
+### Agent MCP Dependencies
+
+Agents can declare MCP dependencies in their routing files:
+
+```markdown
+---
+agent: my-agent
+mcpDependencies:
+  - github
+  - filesystem
+---
+```
+
+The orchestrator overlay includes available MCP servers and their capabilities.
+
+## 8. Manifest Format
+
+`.manifest.json` tracks project-owned files:
+
+```json
+{
+  "version": "1.0",
+  "managedPaths": {
+    "extensions": [".pi/extensions/gentle-agent-extensions.ts"],
+    "agents": [".pi/agents/custom-agent.md"],
+    "routing": [".pi/routing/custom-agent.md"],
+    "overlays": [".pi/overlays/orchestrator.overlay.md"],
+    "skills": ["skills/custom-skill/SKILL.md"],
+    "mcp": ["mcp/server.mcp.json"],
+    "scripts": ["scripts/sync.sh"],
+    "assets": []
+  },
+  "installProfiles": {
+    "pi": { "agentHome": "~/.pi/agent" },
+    "gentle-shell": { "agentHome": "~/.local/share/gentle-shell/agent" }
+  }
+}
+```