---
name: ibgib-implementation-plan
description: Guidelines and template for structuring, creating, and updating persistent [what]_IMPLEMENTATION.md files in the ibgib codebase.
---

# ibgib Implementation Plan (`[what]_IMPLEMENTATION.md`)

This skill defines the structure, conventions, and workflow for creating and maintaining persistent `[what]_IMPLEMENTATION.md` files across the `ibgib` monorepo.

## Purpose

In complex `ibgib` architectural initiatives, single-session AI artifacts (like transient implementation plans or scratch notes) can be lost across chat sessions. A `[what]_IMPLEMENTATION.md` file serves as a **living, persistent design document, execution tracker, and technical decision log** for a specific sub-project or feature milestone (e.g. `VCS_PLANNING_IMPLEMENTATION.md`, `SSO_IMPLEMENTATION.md`, `TS7_IMPLEMENTATION.md`).

## Standard File Location

Implementation plan files should be placed either in:
* `docs/[what]_IMPLEMENTATION.md` (for monorepo-wide or domain initiatives, e.g. `docs/vcs/VCS_PLANNING_IMPLEMENTATION.md` or `docs/VCS_IMPLEMENTATION.md`)
* `docs/[feature]/[what]_IMPLEMENTATION.md` (for targeted domain areas, e.g. `docs/identity/SSO_IMPLEMENTATION.md`)

---

## Standard Structural Schema

Every `[what]_IMPLEMENTATION.md` file MUST follow this high-level structure, adapting or adding sub-sections as relevant:

```markdown
# [Feature / Subsystem Name] Implementation Plan ([WHAT_CODE_NAME])

## 📌 Executive Summary & Architectural Model

*   **Goal & Overview**: Concise summary of what this implementation achieves.
*   **Architectural Principles**: Core domain models, DAG dynamics, trade-offs, security model, and identity integration.
*   **Schemas & Naming Conventions**: Strict naming formats (e.g., kebab-case delimiters, flatcase inner tokens, pool IDs, rel8n labels).

---

## 🛠️ Build Chain & Environment Setup

*   **Workspace Build Chain**:
    *   **Local Library Iteration**: When modifying code in a lower-level library (e.g. `libs/core-gib`), run its specific build and test commands (e.g. `npm run build:core-gib` and `npm run test:core-gib`).
    *   **Downstream Chain Propagation**: After local library changes pass, you MUST propagate changes to downstream dependents by running the appropriate chain build command (e.g. `npm run chain:build:core-gib` or `npm run chain:build:web-gib`).
    *   **Application Builds**: Build and run downstream applications with `npm run build:[app]` or `npm run watch:[app]` (e.g. `npm run build:space-gib`).
*   **Environment Configuration**: Required `.env` variables, port settings, or hardware/OS constraints.

---

## ⏱️ Baseline & Decision Log / Journal

### Baseline Metrics (if performance/refactoring focused)
*   Table of initial timings, size measurements, or code line counts.

### Architectural Decision Log (Journal Entries)
*   **Entry N ([Date])**: Context, root cause analysis, evaluation of alternatives, and finalized resolution.

---

## 📋 Step-by-Step Implementation Checklist

Break the work into small, incremental, independently verifiable steps:

### Step 1: [Component / Sub-system Name]
- [ ] **1.1 [Sub-task Title]**: Description of changes.
  - Linked files: [`basename.mts`](relative/path/to/file.mts#L10-L30)
- [ ] **1.2 [Sub-task Title]**: Description of changes.

### Step 2: [Next Phase / Integration]
- [ ] **2.1 [Sub-task Title]**: Description of changes.

---

## 🤖 Sub-agent Pipeline (Optional)

> [!NOTE]
> **Sub-Agent Pipeline Operational Status (2026-09-30)**:
> Due to cross-context tool permission issues, sub-agent invocations have encountered reliability roadblocks. We have been actively **skipping** the sub-agent pipeline in favor of direct agent execution. We will re-evaluate and test this pipeline again after the next Gemini Flash model release.

When enabled for complex initiatives, an agent pipeline can be configured using the profiles in the [agents folder](.agents/agents).

The standard pipeline structure is:

1. [implementor](.agents/agents/implementor.md)
2. [critic auditor](.agents/agents/critic-auditor.md)
3. [security auditor](.agents/agents/security-auditor.md)
4. [final tester](.agents/agents/tester.md)

*Note: The [implementor](.agents/agents/implementor.md) is structured to use its own [tester sub-agent](.agents/agents/tester.md). If this pipeline is omitted, the primary agent executes the implementation and test verification directly.*

---

## 🧪 Testing & Verification Strategy

> [!IMPORTANT]
> Always review and follow [`docs/RESPEC_GIB_GUIDANCE.md`](../../../docs/RESPEC_GIB_GUIDANCE.md) for respec testing patterns, including the strict use of `ifWeMight` blocks, avoiding artificial delays, and proper error handling.

> [!TIP]
> **Tester Subagents Mandate**: All test execution and log analysis should be delegated to a dedicated **Tester Subagent** spawned with the [tester agent](../../agents/tester.md). The tester subagent reads `RESPEC_GIB_GUIDANCE.md`, runs the canonical test command, and returns only the isolated failure points and stack traces to keep the primary conversation clean.

*   **Unit & Integration Tests**: `respec-gib` test commands (`npm run test:core-gib`, `npm run test:vcs-gib`) and specific `ifWeMight` focus instructions.
*   **Manual & E2E Checks**: Step-by-step verification steps in browser or CLI environment.

---

## 🔌 Upstream Upgrades & Lower-Lib PR Requests (Optional)

_note: these are not PRs proper, because we're not using git. This is just to convey what to do if/when an agent wants to modify a lower lib, which they absolutely should NOT do. If this workaround doesn't work, the agent should stop and explain the blocker, just like any developer working on a complex task._

*   **Application-Level Shims**: List of local shims created in `src/shims/[lib_name]/...` to avoid unvetted modifications to lower-level libraries (anything found in `/libs`, e.g., `libs/helper-gib`, `libs/ts-gib`, etc.).
*   **Proposed Upstream Upgrades**: Descriptions of missing lower-level features or helpers identified during implementation that should be refactored upstream in future iterations.

---

## 💡 Addendum & Backlog

*   **Deferred Scope**: Features explicitly postponed to future iterations.
*   **Technical Debt / Security Alerts**: Notes on future refactoring or alert mechanisms needed.
```

---

## Best Practices & Guidelines

1. **Explicit File Links**: Always use clickable file links using relative file paths (e.g. `[filename.mts](relative/path/to/file.mts)` or `[filename.mts#L10-L20](relative/path/to/file.mts#L10-L20)`).
2. **Incremental Updates**: Update task checkboxes (`- [ ]` $\to$ `- [x]`) and add journal entries in real-time as tasks progress.
3. **Strict Casing & Naming**: Maintain consistency with `ibgib` conventions (flatcase inner tokens, kebab-case component IDs, explicit transform names like `fork`, `mut8`, `rel8`).
4. **Preserve Context**: When starting a new conversation prompt for a sub-task, reference the corresponding `[what]_IMPLEMENTATION.md` file so any agent can instantly regain full architectural context.
5. **Positive Lower-Lib Shim Workflow**:
   * Direct modifications to foundational libraries (`libs/ts-gib`, `libs/core-gib`, `libs/encrypt-gib`, `libs/helper-gib`) should be avoided during application-level feature development unless explicitly authorized.
   * When an agent encounters a limitation or missing helper in a lower-level library, the recommended workflow is to **create a local application shim** inside the application's source directory (e.g., `src/shims/core-gib/space/custom-space-helper.mts` or `src/shims/ts-gib/transforms/custom-transform-shim.mts`).
   * If necessary, WET copy and adapt the required helper logic locally.
   * Document all shims under the **"Upstream Upgrades & Lower-Lib PR Requests"** section in the active `[what]_IMPLEMENTATION.md` file for future upstream monorepo integration.