@timtekno/agentic-template

A ready-to-install pi package for teams that want a consistent agent setup.

Use it to get a standard agent experience with personas, bundled subagents, reusable prompts, and shorter default replies.

What it includes

• ready-to-use resources for agent workflows
• /persona command for switching agent style
• /persona-status command for checking resolved persona sources
• keyboard shortcut to rotate persona
• built-in caveman mode for shorter replies and lower token usage
• coder persona based on Andrej Karpathy's Claude Code guidelines
• extra personas for testing and docs work
• official-style subagent extension adapted from the pi example
• bundled agents: scout, planner, worker, reviewer, tester, debugger, docs-writer, package-auditor
• workflow prompts: /implement, /scout-and-plan, /implement-and-review, /debug, /test-and-fix, /research, /docs-update, /package-audit
• reusable skills for release checks and package audits
• packaged default theme: timtekno-default

Install

Install from npm

pi install npm:@timtekno/agentic-template

Install in the current project only

pi install -l npm:@timtekno/agentic-template

After install, open Pi in your project and start using it right away.

Caveman mode is enabled by default for shorter output.

Personas

Use /persona to switch the agent style when needed.

Persona reads from:

• project setting in .pi/settings.json
• global setting in ~/.pi/agent/settings.json
• session entries as fallback

Resolution order:

• project
• global
• session
• default coder

Available personas:

• coder — implementation-focused, small safe diffs
• analyst — diagnosis and root-cause analysis
• architect — system design and tradeoffs
• tester — verification, regression risk, edge cases
• docs — install, usage, examples, clarity

Commands

/persona
/persona coder
/persona analyst
/persona architect
/persona tester
/persona docs
/persona-status

When run from UI, /persona asks whether to save globally or for current project.

Shortcut

Ctrl+Shift+]

Rotates persona in order and saves globally.

Subagent workflows

Package includes official example-inspired subagent setup.

Built-in agents

• scout — fast codebase recon
• planner — implementation planning only
• worker — general implementation agent
• reviewer — review and feedback agent
• tester — validation and regression risk review
• debugger — failure-path and root-cause analysis
• docs-writer — docs planning and wording help
• package-auditor — publish readiness and package surface audit

Built-in agents do not pin a provider model by default unless their frontmatter says otherwise. They inherit your active Pi model settings.

Subagent tool features

subagent supports:

• single mode: { agent, task }
• parallel mode: { tasks: [...] }
• chain mode: { chain: [...] }
• agentScope: user, project, or both
• project-agent confirmation prompt by default
• optional per-run or per-step model
• optional per-run or per-step timeout
• optional per-run or per-step retry

Agent commands

/agents
/agent-sources
/validate-agents

• /agents lists resolved winning agents
• /agent-sources shows bundled, user, and project agent paths plus override chain
• /validate-agents reports malformed or conflicting agent files

Prompt templates

/implement <task>
/scout-and-plan <task>
/implement-and-review <task>
/debug <task>
/test-and-fix <task>
/research <task>
/docs-update <task>
/package-audit <task>

Notes

• bundled agents ship inside package under extensions/subagent/agents
• project-local agents can still be loaded from .pi/agents
• user-level agents can still be loaded from ~/.pi/agent/agents
• project agents override user and bundled agents with same name when enabled via agentScope
• /validate-agents surfaces duplicate names and malformed frontmatter

Skills

Package ships reusable skills under skills/:

• release-checklist
• package-audit

Use them when preparing releases or checking npm/package quality.

Theme

Package ships one theme under themes/default.json:

• timtekno-default

Select it from Pi settings after install.

Contributor scripts

npm run typecheck
npm run test
npm run smoke:package
npm run publish:package -- <patch|minor|major>

• typecheck checks package script syntax
• test runs lightweight validation tests for settings and subagent wiring
• smoke:package verifies publish payload via dry-run pack
• publish:package runs release workflow script

Publish notes

Safe publishing workflow:

1. run npm run publish:package -- <patch|minor|major>
2. let script bump version and publish
3. review git diff
4. commit and push source changes separately