Pi Agentic Engineer

My personal Pi.dev / Pi-based Agentic Engineer designed for spec-driven development, deterministic execution phases, context isolation, test-first enforcement, automated verification, explicit memory, and safe Git integration.

This setup has been upgraded from a single rigid agent into a Global Meta-Architecture featuring a Senior Technical Consultant persona that orchestrates specialized, isolated subagents for coding tasks.

Core Philosophy

This environment enforces a linear, deterministic pipeline: IDEA → SPEC → PLAN → IMPLEMENT → VERIFY → REFLECT → COMMIT

Key rules:

• Spec as Law: No coding without an approved spec file in the specs/ directory.
• Context Isolation: Each development phase runs in a fresh subagent process. No conversational carryover is allowed.
• Tests as Enforcement: Tests are written before implementation and must fail initially (Red Phase).
• Memory is Explicit: Never trust conversational state. If it is not in a file, it does not exist.
• Architecture over Improvisation: Challenge bad assumptions, explicitly object to suboptimal approaches, and optimize for long-term viability.
• Verification Gates Commits: Git commits automatically reference Spec-ID + Task-ID, but only after passing automated quality gates.

---

Global System Architecture

Instead of hardcoding rules per project, this setup uses a Global Brain (~/.pi/agent/) that interacts with local project folders.

1. The Global Meta-Agent (AGENTS.md)

The default Pi persona is a Senior Technical Consultant, Systems Architect, and Troubleshooter. It does not blindly write code. It follows a strict flow: Problem reframing → Diagnosis → Options → Recommendation → Action. When you are ready to build, it delegates the work to isolated subagent chains.

2. The Specialized Subagents & Chains

Located in ~/.pi/agent/agents/ and ~/.pi/agent/prompts/. Complex operations are piped between specialized subagents using {previous} context handoffs.

• spec-and-plan: Analyzes requirements to output a Markdown spec and a derived .pi/runs/<id>/tasks.yaml.
• test-and-implement: Enforces the Red/Green phase by chaining the Test Engineer (writes failing tests) to the Implementer (writes code to pass tests).
• verify-and-commit: Runs linters, type-checks, and auto-repairs, culminating in a structured Git commit.

3. The Global Memory Vault

Persistent files (AGENTS.md, MEMORY.md, SOUL.md, SCRATCHPAD.md, and /daily/, /notes/ folders) live centrally in ~/.pi/agent/memory/ and are symlinked into local projects.

---

Installed Tooling

Quality Enforcement (Local Python Example)

Your system must defend against bad code.

pip install pytest ruff mypy pre-commit

Pi Extensions & Plugins

Installed globally via pi install or NPM:

• @aliou/pi-guardrails (Prevents unsafe operations)
• pi-updater (Updates Pi & Extensions)
• pi-context (File-scoped awareness)
• git:github.com/jo-inc/pi-mem (Explicit memory layer)
• git:github.com/jo-inc/pi-reflect (Post-execution reflection)
• Vendored Subagent Orchestrator: Located in ~/.pi/agent/extensions/subagent/ for parallel execution and chaining.

(Note: pi-planning-with-files has been deprecated in favor of native subagent YAML planners).

---

Usage Guide: The Deterministic Pipeline

Phase 1: Project Initialization & The Symlink Bridge

Instead of manual folder creation, run your global init-spec-project.sh script inside an empty project folder. This instantly:

1. Creates specs/, src/, tests/, and .pi/runs/ directories.
2. Generates strict templates (specs/template.md, .pi/tasks_template.yaml, .git/.commit_template).
3. Sets up .pre-commit-config.yaml to defend against trailing whitespace and syntax errors.
4. Bridges Global Memory: Creates symlinks to ~/.pi/agent/memory/AGENTS.md, MEMORY.md, SOUL.md, and SCRATCHPAD.md so the project shares your global brain seamlessly.

Phase 2: Spec Creation & Task Planning

Trigger: /spec-and-plan [your idea]

• The spec-engineer subagent drafts the specification using your strict template.
• Acceptance criteria must be machine-testable.
• Once approved, the output is passed to the planner subagent, which decomposes the spec into a static .pi/runs/<spec-id>/tasks.yaml file.

Phase 3: The Red/Green Implementation Loop

Trigger: /test-and-implement [Task-ID]

• Red Phase: The test-engineer subagent reads the YAML task and generates failing tests in an isolated context. The tests must fail initially.
• Green Phase: The implementer subagent receives the failing test outputs and writes the minimal src/ code required to pass them. It is forbidden from modifying the tests.

Phase 4: Verification & Auto-Commit

Trigger: /verify-and-commit

• The verifier subagent runs pytest, ruff check ., and mypy ..
• If checks fail, it triggers a minimal auto-repair loop (max 3 retries).
• Once perfectly green, it updates tasks.yaml to completed and executes a Git commit formatted explicitly as feat(<spec-id>): <description> (<task-id>).

---

Daily Rhythm & Memory Operations

You must actively manage the agent's memory. Never trust conversational state.

Start of Session (Hygiene)

Force the global memory into the agent's context window:

memory_read list
memory_read MEMORY.md
memory_read SCRATCHPAD.md

Audit Tip: Run Show me the files that were injected into your context right now to verify deterministic awareness.

End of Session (Consolidation)

Turn experience into durable rules:

• Run /reflect after major implementation phases or failures.
• Accept pi-reflect proposals to update MEMORY.md and AGENTS.md.
• Groom SCRATCHPAD.md (keep under 30 lines; unresolved items equal future pain).

---

What This Environment Is Not

• Not autonomous chaos.
• Not conversational coding.
• Not improvisational editing.
• Not a generic AI assistant.

It is a controlled, file-driven, spec-enforced agentic development pipeline. The integrity of the system depends on discipline.

---

Author & Attribution

Created and maintained by: Barış Parlan (@bparlan | https://twitter.com/bparlan)

This repository reflects an ongoing exploration of deterministic agentic development, spec-driven architecture, and disciplined AI-assisted engineering workflows.