Introducing a new way to review your PRs.

Read the announcement

affaan-m / ecc

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

View on GitHub

30 documents · Updated Nov 20, 2026

docs / pi-core-capability-bundle

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 --check to detect committed drift.
  • Keep a shipped skill's frontmatter name aligned with its source directory, except for the declared council to ecc-council bundle 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

TriggerConsequenceGuard
A new root skill or command is not classifiedThe bundle cannot be rebuilt safely because content can bypass curationManifest partition checks in build-pi-core.js
Included text contains an unapproved endpoint, secret pattern, runtime fetch-and-run form, or absolute home pathThe build rejects the profile as unsafe or non-portableManifest safety rules and build scans
pi/core/ is not regenerated after a source or manifest changeRelease content differs from the declared selectionDeterministic --check drift comparison
Pi starts but does not discover the expected prompt filesA consumer receives an incomplete command surfaceOffline load check compares discovered commands with the manifest
A release uses an unsigned or wrong-commit tagThe release identity is not trustedAnnotated signed-tag and exact-commit checks
CI or CodeQL results belong to another run, commit, or category setRelease approval can reflect the wrong validationTrusted workflow, run-attempt, job, and check binding

Key files

FileWhy to read it
manifests/pi-core.jsonDefines the Pi Core scope, package metadata, renames, exclusions, and safety policy.
pi/…/package.jsonShows the package identity and the Pi resource paths that consumers load.
pi/…/README.mdShows the consumer-facing package purpose, loading path, offline check, and regeneration rule.
pi/…/CURATION.mdShows the selected catalog size and the reasons content stays outside the portable profile.
scripts/build-pi-core.jsExplains how the curated profile is assembled, checked, scanned, and regenerated.
pi/…/code-review.mdIllustrates the portable local and pull request review workflow exposed as a prompt command.
scripts/…/pi-core-load-test.jsShows how offline Pi startup and prompt discovery are validated.
scripts/…/verify-release-gates.jsDefines the tag, exact-commit, CI, and CodeQL conditions for release approval.