gentle-agent-extensions

Bundled extensions for Gentle Shell: architecture-quest, architecture-council, orchestrator overlay, and more

Packages

Package details

extensionskill

Install gentle-agent-extensions from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:gentle-agent-extensions

Package: gentle-agent-extensions
Version: 1.2.0
Published: Nov 1, 2026
Downloads: 411/mo · 411/wk
Author: andy-technologies
License: Apache-2.0
Types: extension, skill
Size: 65.9 KB
Dependencies: 0 dependencies · 5 peers

Pi manifest JSON

{
  "skills": [
    "resources/skills/*"
  ],
  "themes": [],
  "prompts": [],
  "extensions": [
    "src/extension.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

gentle-agent-extensions

Bundled extensions for Gentle Shell — Install once, get architecture-quest, architecture-council, orchestrator overlay, and gentle-agent-extension skill automatically. No configuration needed.

What This Package Provides

Resource	Description
architecture-council agent	Read-only contractual verifier for Architecture Quest contracts
architecture-quest skill	Explores architectural needs, identifies gaps, produces verifiable contracts
gentle-agent-extension skill	Teaches how to extend this package (for maintainers)
orchestrator.overlay.md	Integrates Quest + Council into ODD workflow before RDD review
architecture-council routing	Semantic delegation rules for the council agent

What This Package Does NOT Do

❌ Require user project directories (agents/, overlays/, skills/)
❌ Need sync.sh, doctor.sh, install.sh scripts (removed)
❌ Modify Gentle AI or Gentle Pi official repositories
❌ Create parallel agent registries or skill indexes

Installation

From npm (recommended)

pi install npm:gentle-agent-extensions@latest

From Git

pi install git:github.com/AndyTechnologies/gentle-agent-extensions@v1.2.0

Local development

pi install ./gentle-agent-extensions
# Or for testing without installing:
pi -e ./src/extension.ts

That's it. No scripts, no sync, no doctor. Open Pi and everything works.

Usage

Automatic on Session Start

When you open Pi, the extension:

Copies bundled agents to your project's .pi/agents/
Registers bundled MCP servers (when added)
Applies bundled overlays to orchestrator and agents
Skills are auto-registered via pi.skills

Commands (inside Pi)

Command	Description
`/gentle-extensions:status`	Show bundled resources status
`/gentle-extensions:sync`	Re-sync bundled agents to current project
`/gentle-extensions:doctor`	Validate bundled resources + installation
`/gentle-extensions:mcp-reload`	Reload MCP servers from bundled resources
`/gentle-extensions:fix`	Auto-fix non-destructive issues
`/gentle-extensions:mcp-health`	Test MCP connectivity (stdio + HTTP)
`/gentle-extensions:conflicts`	Interactive conflict resolution

Delegation

# Architecture Council - verify architectural contract
"Use architecture-council to verify AC-01"

# Architecture Quest - explore architectural decisions
"Run architecture quest for this feature"

Skills

Skills are auto-available via /skill-registry:refresh:

architecture-quest — Architectural exploration
gentle-agent-extension — Package maintainer guide

Architecture

~/.pi/agent/npm/node_modules/gentle-agent-extensions/   ← Installed package (read-only)
├── src/extension.ts                                     ← Pi extension entry point
├── resources/
│   ├── agents/architecture-council.md                   ← Bundled agent
│   ├── overlays/orchestrator.overlay.md                 ← Bundled overlay
│   ├── skills/
│   │   ├── architecture-quest/SKILL.md                  ← Bundled skill
│   │   └── gentle-agent-extension/SKILL.md              ← Bundled skill
│   ├── routing/architecture-council.md                  ← Bundled routing
│   └── mcp/                                             ← Bundled MCPs (future)
├── package.json                                         ← pi: {extensions, skills}
└── README.md

How It Works

pi install downloads package to ~/.pi/agent/npm/node_modules/gentle-agent-extensions/
Pi loads src/extension.ts via pi.extensions in package.json
session_start: Extension reads bundled resources from resources/ (using import.meta.url)
before_agent_start: Applies overlays, injects MCP info to orchestrator
Skills loaded via pi.skills: ["resources/skills/*"] in package.json

For Package Maintainers

Adding a New Bundled Agent

# 1. Create agent in resources/agents/
cat > resources/agents/my-agent.md <<'EOF'
---
name: my-agent
description: "What this agent does"
model: anthropic/claude-opus-4
thinking: high
mode: task
tools: [read, write, bash]
---
# My Agent Instructions
EOF

# 2. Add routing in resources/routing/
cat > resources/routing/my-agent.md <<'EOF'
---
agent: my-agent
triggers: ["trigger phrase"]
delegation: subagent_run
---
EOF

# 3. (Optional) Add skill in resources/skills/
mkdir -p resources/skills/my-agent
cat > resources/skills/my-agent/SKILL.md <<'EOF'
---
name: my-agent
description: "Trigger: trigger phrase. Delegates to my-agent."
license: Apache-2.0
metadata:
  author: AndyTechnologies
  version: "1.0"
---
# My Agent Skill
## Activation Contract
Use when...
## Hard Rules
- Only delegate via subagent_run to my-agent
## Decision Gates
| Situation | Action |
| "trigger phrase" | Delegate to my-agent |
| General coding | Do NOT delegate |
## Execution Steps
1. Call subagent_run with agent=my-agent
2. Return results
## Output Contract
Findings with severity
## References
- resources/agents/my-agent.md
- resources/routing/my-agent.md
EOF

Adding a Bundled Overlay

cat > resources/overlays/target-agent.overlay.md <<'EOF'
---
target: target-agent
priority: 100
mode: append
---
# Additional Instructions for target-agent
EOF

Modes: append (default), prepend, replace

Adding a Bundled MCP Server

cat > resources/mcp/my-server.mcp.json <<'EOF'
{
  "name": "my-server",
  "description": "What this server provides",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@pkg/server"],
  "env": { "API_KEY": "${API_KEY}" },
  "exposure": "codemode",
  "enabled": true
}
EOF

Test Locally

# Test without installing
pi -e ./src/extension.ts

# In Pi:
/gentle-extensions:status
/gentle-extensions:doctor

Publish

npm version patch  # or minor/major
git push origin main --tags
npm publish --access public

Configuration

`extension.config.json` (optional)

Override defaults in the package root:

{
  "features": {
    "autoSync": true,
    "versionTracking": true
  },
  "validation": {
    "requireLicense": true,
    "allowUnknownTargets": true
  },
  "mcpDefaults": {
    "timeout": 60,
    "exposure": "codemode"
  }
}

Peer Dependencies

Pinned to Pi 1.4.0 compatible versions:

"peerDependencies": {
  "@earendil-works/pi-coding-agent": "^1.4.0",
  "@earendil-works/pi-agent-core": "^1.4.0",
  "@earendil-works/pi-ai": "^1.4.0",
  "@earendil-works/pi-tui": "^1.4.0",
  "typebox": "^0.30.0"
}

Development

Run Tests

# Unit tests (fast)
node --test tests/gentle-extensions.test.ts

# Integration tests (slow, spawns Pi)
node --test tests/integration.test.ts

Test Without Installing

pi -e ./src/extension.ts
# Then in Pi:
/gentle-extensions:status

gentle-agent-extensions

What This Package Provides

What This Package Does NOT Do

Installation

From npm (recommended)

From Git

Local development

Usage

Automatic on Session Start

Commands (inside Pi)

Delegation

Skills

Architecture

How It Works

For Package Maintainers

Adding a New Bundled Agent

Adding a Bundled Overlay

Adding a Bundled MCP Server

Test Locally

Publish

Configuration

extension.config.json (optional)

Peer Dependencies

Development

Run Tests

Test Without Installing

Compatibility

License

References

`extension.config.json` (optional)