Pi Core capability bundle
Pi Core is a curated Pi distribution of portable ECC engineering skills and prompt-workflow commands. It gives a Pi coding agent a stable capability set that can run without extensions, hooks, network access, runtime downloads, or SaaS services. This page complements the agent catalog and prompts overview and relates to agent roles and command surface and skills, contexts, and language rules.
Bundle purpose
Portable engineering capabilities
The bundle gives Pi a focused set of engineering guidance for language and framework work, testing, code review, security review, planning, refactoring, documentation, and Git or pull request work. It also covers agent security boundaries, change impact, domain context, documentation governance, module regression, test evidence, and Bengali text processing.
These capabilities help an agent reason about code and delivery work without depending on the wider ECC control system. They remain guidance and prompt workflows rather than a second runtime or a network service.
References: pi/…/README.md• L1-12 scripts/build-pi-core.js• L3-14 pi/…/SKILL.md• L8-19 pi/…/SKILL.md• L8-19 pi/…/SKILL.md• L7-30 pi/…/SKILL.md• L7-22 pi/…/SKILL.md• L8-23 pi/…/SKILL.md• L30-48 pi/…/SKILL.md• L31-50
Prompt workflow commands
The command set turns common engineering tasks into portable prompt workflows. The code-review command supports both local change review and pull request review, with findings, validation, and a review decision as its intended output.
The command is still content loaded by Pi. It does not add a special agent roster or extension runtime to the package.
References: manifests/pi-core.json• L353-378 pi/…/code-review.md• L14-26 pi/…/code-review.md• L76-79 pi/…/code-review.md• L173-190
Curated content boundary
The Pi Core manifest is the source of truth for the bundle boundary. It classifies every root skill and command as included or excluded with a reason. This complete partition prevents new catalog content from entering the package without a curation decision.
The bundle excludes content that depends on runtime network access, secret-backed services, third-party SaaS, commercial ECC products, Claude Code-only session or orchestration features, and narrow domain or offensive security work. The selected skills must remain portable and self-contained even when they describe project-level tools or external documentation.
References: manifests/pi-core.json• L12-31 manifests/pi-core.json• L33-171 manifests/pi-core.json• L353-454 pi/…/CURATION.md• L3-16
Package contract
Pi resource interface
The package contract tells Pi where to load the two supported resource types. The ecc-pi-core package exposes ./skills as skills and ./commands as prompt resources. It does not expose an extension entry point, so the bundle supplies content and prompts rather than a plug-in runtime.
The package uses the root repository version and MIT license. The current generated package version is 2.2.3. A curated rename changes council to ecc-council inside the bundle so the shipped name is unique, while the root skill keeps its original name.
References: pi/…/package.json• L1-17 scripts/build-pi-core.js• L116-167
Generated profile contents
The committed pi/core/ directory is the release form of the package. It contains the selected skills and commands together with the license, usage guide, and curation record. Consumers can copy this directory or pin a release tarball without rebuilding the selection.
The profile currently represents 132 selected skills and 24 selected commands. The curation record also explains why the remaining root catalog content is outside the portable profile.
References: pi/…/README.md• L3-12 pi/…/CURATION.md• L1-4 scripts/build-pi-core.js• L158-253
Build process
Manifest-driven assembly
The build creates a deterministic profile from the manifest and the root catalog. It copies selected skill directories and command files, applies declared renames, writes package metadata, and generates the README and curation record. A normal build replaces the committed profile only after all checks pass.
The build also checks that every on-disk root skill and command has one manifest classification. A missing classification or a manifest entry for missing source content stops the build before an unreviewed mismatch can reach the package.
References: scripts/build-pi-core.js• L41-77 scripts/build-pi-core.js• L111-167 scripts/build-pi-core.js• L216-253 scripts/build-pi-core.js• L387-390
Content safety validation
The build treats the profile as an offline content set. It rejects unapproved callable URLs, secrets, runtime fetch-and-run patterns, absolute user-home paths, symlinks, invalid skill metadata, duplicate shipped names, and excessive total skill-description text.
The safety policy distinguishes documentation links and reader-run project setup examples from downloads performed by the bundle itself. The manifest holds scoped scan exceptions with reasons, so approved anti-pattern examples can remain visible without weakening the general safety checks.
References: manifests/pi-core.json• L456-505 scripts/build-pi-core.js• L15-30 scripts/build-pi-core.js• L256-350
Drift check
The --check mode builds a temporary profile and compares its file list and bytes with the committed pi/core/ directory. It does not change the committed profile. Any difference means that the manifest or included source changed without regenerating the release form.
References: scripts/build-pi-core.js• L32-34 scripts/build-pi-core.js• L360-384
Delivery validation
Offline Pi load
The load check proves that Pi can start with the bundle while offline and with sessions, context files, and extensions disabled. It then checks that Pi discovers the expected prompt commands. This validates both process startup and the resource contract that consumers use.
The delivery path moves from curated source to a generated package and then to a real Pi load:
flowchart LR
M[Pi Core manifest] --> B[Deterministic profile build]
B --> P[Committed pi/core package]
P --> L[Offline Pi load]
L --> C[Discovered prompt commands]
C --> V[Manifest selection check]
References: pi/…/README.md• L14-28 scripts/…/pi-core-load-test.js• L3-20 scripts/…/pi-core-load-test.js• L29-49 scripts/…/pi-core-load-test.js• L84-110
Release gate verification
Release verification protects the commit that carries the bundle. It requires a supported annotated and cryptographically verified tag that points to the checked-out release commit. It then requires successful CI and CodeQL results for that exact commit on main.
The CodeQL policy requires trusted results for Actions, JavaScript or TypeScript, and Python. The verifier binds results to the selected run attempt and rejects missing, duplicated, changed, or unexpected results. A tag-only recheck confirms that an existing tag still points to the same tag object.
References: scripts/…/verify-release-gates.js• L6-19 scripts/…/verify-release-gates.js• L45-72 scripts/…/verify-release-gates.js• L213-235 scripts/…/verify-release-gates.js• L265-295 scripts/…/verify-release-gates.js• L305-355
Change checklist
When these files or sections are changed, remember to consider these:
- Update the include or exclude classification whenever a root skill or command is added, removed, or renamed. The build requires a complete partition.
- Regenerate
pi/core/after changing the manifest, an included skill, an included command, the root version, or the root license. Use--checkto detect committed drift. - Keep a shipped skill's frontmatter name aligned with its source directory, except for the declared
counciltoecc-councilbundle rename. - Review safety allowlists and curation reasons together when included content gains a URL, install example, path, or security warning.
- Keep manifest command names, the generated prompt tree, and the offline load check's expected set aligned.
- Treat changes to the release tag, release commit, CI workflow, or CodeQL categories as release-policy changes. The exact-SHA gate checks all of these links.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A new root skill or command is not classified | The bundle cannot be rebuilt safely because content can bypass curation | Manifest partition checks in build-pi-core.js |
| Included text contains an unapproved endpoint, secret pattern, runtime fetch-and-run form, or absolute home path | The build rejects the profile as unsafe or non-portable | Manifest safety rules and build scans |
pi/core/ is not regenerated after a source or manifest change | Release content differs from the declared selection | Deterministic --check drift comparison |
| Pi starts but does not discover the expected prompt files | A consumer receives an incomplete command surface | Offline load check compares discovered commands with the manifest |
| A release uses an unsigned or wrong-commit tag | The release identity is not trusted | Annotated signed-tag and exact-commit checks |
| CI or CodeQL results belong to another run, commit, or category set | Release approval can reflect the wrong validation | Trusted workflow, run-attempt, job, and check binding |
Key files
| File | Why to read it |
|---|---|
| manifests/pi-core.json | Defines the Pi Core scope, package metadata, renames, exclusions, and safety policy. |
| pi/…/package.json | Shows the package identity and the Pi resource paths that consumers load. |
| pi/…/README.md | Shows the consumer-facing package purpose, loading path, offline check, and regeneration rule. |
| pi/…/CURATION.md | Shows the selected catalog size and the reasons content stays outside the portable profile. |
| scripts/build-pi-core.js | Explains how the curated profile is assembled, checked, scanned, and regenerated. |
| pi/…/code-review.md | Illustrates the portable local and pull request review workflow exposed as a prompt command. |
| scripts/…/pi-core-load-test.js | Shows how offline Pi startup and prompt discovery are validated. |
| scripts/…/verify-release-gates.js | Defines the tag, exact-commit, CI, and CodeQL conditions for release approval. |