toga-ai 1.0.0

package/skills/harness-audit/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: harness-audit
+description: Audits the health of the TOGA Technology team Claude knowledge repo. Runs validation, checks completeness, scores 0-100, and provides top action items. Trigger when the user says "harness-audit", "audit the knowledge base", "check the harness", "how healthy is the knowledge base", or "score the repo".
+---
+
+# Harness Audit — check the health of the team knowledge repo
+
+Perform a full health check of this repo and provide a scored report with concrete
+action items. The goal is to catch drift, missing content, and integrity failures
+before they cause problems in coding sessions.
+
+---
+
+## Step 1 — Locate the team repo
+
+Use the same resolution order as `kickoff`:
+1. Claude memory `team-repo-path`
+2. Env var `CLAUDE_TEAM_REPO`
+3. Auto-discover (`./claude`, `../claude`, `../../claude`, walk up for `knowledge/INDEX.md`)
+4. Ask
+
+From here, all commands use `node "<TEAM_REPO>/knowledge.js" …` and
+`node "<TEAM_REPO>/scripts/harness.js" …`.
+
+---
+
+## Step 2 — Run automated checks
+
+### Check 1: Validation
+```sh
+node "<TEAM_REPO>/knowledge.js" validate
+```
+- **PASS:** output contains "validate: OK" and exit code 0
+- **FAIL:** any `ERROR:` lines in output or non-zero exit code
+- **Report:** count of errors, list first 5 error lines
+
+### Check 2: Harness status
+```sh
+node "<TEAM_REPO>/scripts/harness.js" status
+```
+Collect and display:
+- Number of registered repos
+- Doc counts per framework (broken down by type)
+- Client count and doc counts
+- Last git commit date on `knowledge/`
+
+### Check 3: Architecture coverage
+For every repo in `registry.json`, check that
+`knowledge/<framework>/apps/<repo>/architecture.md` exists.
+- **PASS:** all repos have an architecture.md
+- **FAIL:** list the specific missing paths
+
+### Check 4: INDEX.md integrity
+Check `knowledge/INDEX.md` for the "Auto-generated" notice. Check each
+`<fw>/apps/<repo>/INDEX.md` for the `| Doc |` table header (generated by `knowledge.js index`).
+- **PASS:** all INDEX files appear auto-generated
+- **FAIL:** list any INDEX.md files that look hand-edited (missing table structure)
+
+Additionally, run `git -C "<TEAM_REPO>" log --oneline -- "*/INDEX.md"` and check
+whether any INDEX.md commits were made by a human (non-`knowledge.js` author). Flag
+these as warnings.
+
+### Check 5: clients/ directory
+Check that `knowledge/clients/` exists.
+- **PASS:** directory exists (even if empty)
+- **FAIL:** directory missing — client knowledge has not been started
+
+### Check 6: 1.0/standards/ coverage
+Check `knowledge/1.0/standards/` for at least one `.md` file.
+- **PASS:** at least one standard exists
+- **FAIL:** directory empty or missing — 1.0 has no documented standards
+
+### Check 7: 2.0/standards/ coverage
+Check `knowledge/2.0/standards/` for at least one `.md` file.
+- **PASS:** at least one standard exists
+- **FAIL:** directory empty or missing — 2.0 has no documented standards
+
+### Check 8: Frontmatter completeness
+For every doc in `knowledge/` (excluding INDEX.md files), verify presence of
+required frontmatter: `title`, `framework`, `type`, `status`, `project`.
+- **PASS:** all docs have all required fields
+- **FAIL:** list docs with missing fields (up to 5; note count if more)
+
+---
+
+## Step 3 — Score and report
+
+Each check is worth equal weight (100 / 8 = 12.5 points each, rounded).
+Partial credit is not awarded — a check either passes or fails.
+
+Present results in this format:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Harness Audit — TOGA Technology Claude Knowledge Repo
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  ✓ [PASS] knowledge.js validate
+  ✓ [PASS] registry.json has entries (5 repos)
+  ✗ [FAIL] all repos have architecture.md
+           → Missing: 1.0/apps/library/architecture.md
+  ✓ [PASS] INDEX.md files appear auto-generated
+  ✓ [PASS] clients/ directory exists
+  ✓ [PASS] 1.0/standards/ has standards (1 file)
+  ✓ [PASS] 2.0/standards/ has standards (1 file)
+  ✗ [FAIL] all docs have required frontmatter
+           → 2.0/apps/worker2/features/clickup.md: missing "project"
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Score: 75/100  (6/8 checks passed)
+
+Top 3 action items:
+  1. Create knowledge/1.0/apps/library/architecture.md
+     Run /capture after any Library session to generate this.
+  2. Fix frontmatter in 2.0/apps/worker2/features/clickup.md: add "project: Worker"
+     Then run: node knowledge.js validate
+  3. [next failing check...]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Step 4 — Action item guidance
+
+For each failing check, provide a specific actionable fix (not a vague suggestion):
+
+| Check | Specific fix |
+|-------|-------------|
+| validate fails | Run `node knowledge.js validate`, read each `ERROR:` line, fix the listed file/frontmatter |
+| missing architecture.md | Run `/capture` after the next session on that repo — architecture docs are created then |
+| hand-edited INDEX.md | Run `node knowledge.js index` to regenerate — do NOT re-hand-edit |
+| clients/ missing | Run `mkdir knowledge/clients && touch knowledge/clients/.gitkeep` |
+| standards/ empty | During the next session on that framework, include a standards update in `/capture` |
+| missing frontmatter | Open the file, add the missing field per `knowledge/CONVENTIONS.md` template, re-run validate |
+
+After listing action items, offer: "Would you like me to fix any of these now?"
+If the developer says yes, execute the fixes one at a time and re-run `validate` after
+each write.
+
+---
+
+## Notes
+
+- A score of 100 means the knowledge base is structurally complete and valid.
+  It does NOT mean the content is high quality — quality is a human judgment.
+- A score below 60 means the knowledge base has significant structural problems
+  that will cause `kickoff` or `capture` to produce unreliable results.
+- Run `/harness-audit` before any major PR to the `claude` repo to confirm nothing
+  was inadvertently broken.
+- The `PostToolUse` hook in `.claude/settings.json` auto-validates any write to
+  `knowledge/` files, so most integrity errors are caught at the moment of writing.
+  This audit catches structural and coverage gaps that validate doesn't check.

package/skills/kickoff/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: kickoff
+description: Start-of-session context loader for TOGA Technology projects. Run this at the BEGINNING of a coding session to prime Claude with the right knowledge before writing any code. It asks what you're working on (framework 1.0/2.0/both, front/back/hybrid, which repo/project, which client) and loads the matching coding standards, framework-core architecture, the repo's knowledge, and relevant client knowledge from the team `claude` knowledge base. Trigger whenever the user says "kickoff", "start a session", "prime me", "I'm starting work on X", or "load context for repo/client".
+---
+
+# Kickoff — prime a coding session from the team knowledge base
+
+Load the right knowledge before the developer starts coding. **Never assume missing
+facts — ask.** Heuristics may pre-fill a *suggested default* in a question, but record
+nothing without confirmation.
+
+## Core data model (this is the structure you maintain — same as `knowledge/CONVENTIONS.md`)
+
+- The team knowledge lives in the **`claude` repo** under `knowledge/`.
+- **Framework partitions everything:** `1.0/` (the `App_` framework, core repo `library`)
+  and `2.0/` (the `_underscore` framework, core repo `_underscore`).
+- Within a framework: `apps/<repo>/architecture.md` + `apps/<repo>/features/*.md`, and
+  `standards/*.md`. App folders are keyed by **repo name** (e.g. `worker2`), not project name.
+- Client-specific knowledge is shared at the top level: `clients/<client>/{profile.md,
+  features/, workflows/}`, each doc tagging its `framework`.
+- `knowledge/registry.json` maps **repo ↔ project ↔ framework ↔ role(core|app) ↔ dependsOn**.
+- Every repo implicitly depends on its framework's `core` repo; `dependsOn` adds more.
+
+## Step 1 — Resolve the team-repo (`claude`) path
+
+You need this to read the registry and knowledge. Resolve in order; **persist the result
+to Claude memory** so you never ask twice:
+
+1. **Claude memory** — a `reference` memory named `team-repo-path` (recalled memories
+   appear in your context). Use it if present and it contains `knowledge/INDEX.md`.
+2. **Env var** `CLAUDE_TEAM_REPO`.
+3. **Auto-discover** — probe `./claude`, `../claude`, `../../claude`, and walk up the tree
+   for a directory containing `knowledge/INDEX.md`.
+4. **Ask** the developer: "Where is the team `claude` repo checked out on this machine?"
+
+When resolved, if there was no `team-repo-path` memory, **write one** (memory type
+`reference`) and add its `MEMORY.md` pointer. From here on call the helper as
+`node "<TEAM_REPO>/knowledge.js" <command>`.
+
+## Step 2 — Interview the developer (ask the work questions FIRST)
+
+Ask these in one message. **Present the repos/projects you already know** (read
+`registry.json`) so the developer can just pick:
+
+1. **Framework** — 1.0, 2.0, or **both**?
+2. **Layer** — front-end, back-end, or hybrid?
+3. **Repo / project** — list the registered repos for the chosen framework(s) as options
+   (show `repo` and `project`), plus **"a new repo not listed"**. If they pick the new-repo
+   option, run **New-repo onboarding** (below) before continuing.
+4. **Client** — which client is this for, or "shared / internal"? (List `clients/` folders
+   you know of, plus "a new client".)
+5. **What are you building or changing?** (a sentence — used to pick relevant feature docs.)
+
+If any answer is unclear, ask again. Do not guess the framework, repo, project, or client.
+
+## Step 3 — Resolve the repos this work needs (local paths, lazily)
+
+Compute the load set with `node "<TEAM_REPO>/knowledge.js" deps --repo=<chosen-repo>`
+(returns the framework core + chosen repo + transitive `dependsOn`, in load order). For
+**both** frameworks, run it for each chosen repo and union the results.
+
+For **each** repo in the load set, get its local path so you can navigate the actual code:
+- Look for a Claude `reference` memory named `repo-path-<repo>` (e.g. `repo-path-worker2`).
+- If absent, **ask**: "What is the path to the `<repo>` repository?" Validate it exists,
+  then **write a `repo-path-<repo>` memory** (+ MEMORY.md pointer).
+
+Never ask for a repo the session doesn't touch.
+
+## Step 4 — Load the knowledge
+
+Read and internalize, in this order:
+1. **Framework core architecture** — `<TEAM_REPO>/knowledge/<fw>/apps/<core-repo>/architecture.md`
+   (e.g. `2.0/apps/_underscore/architecture.md`). Always load this first.
+2. **The chosen repo's** `architecture.md`, then feature docs matched to the description:
+   `node "<TEAM_REPO>/knowledge.js" search --framework=<fw> --repo=<repo> --q=<keywords>`.
+3. **Coding standards** for the framework(s): `<fw>/standards/backend-php.md` and/or
+   `frontend.md` per the layer answer (plus any others that exist). Load whichever exist.
+4. **Client knowledge** (if a real client): `clients/<client>/profile.md` and that client's
+   `features/`/`workflows/` filtered to the selected framework(s)
+   (`search --client=<client> --framework=<fw>`).
+
+For **both** frameworks, union across `1.0/` and `2.0/`.
+
+**Do NOT create or modify any `CLAUDE.md` stub** — kickoff only reads. A blank session is a
+valid choice; this skill is opt-in.
+
+## Step 5 — Summarize and confirm
+
+Tell the developer concisely:
+- Which framework(s), repo(s), and client are in scope, and the local path of each repo.
+- Which knowledge docs you loaded (by title). Where a repo/standard has **no knowledge yet**,
+  say so explicitly: "No knowledge captured yet for X — `capture` will build it as you work."
+- Confirm you're primed and ready for their first task.
+
+## New-repo onboarding (when the developer names a repo not in `registry.json`)
+
+Ask **all** of the following — assume nothing (you may offer a suggested default, e.g.
+framework based on whether the path is under a 1.0 or 2.0 tree, but require confirmation):
+
+1. **Repo name** — the exact on-disk folder/repo name.
+2. **Framework** — 1.0 or 2.0.
+3. **Project name** — the logical name.
+4. **Role** — framework **core** or regular **app**?
+5. **dependsOn** — any other repos it depends on beyond the framework core? (default none)
+6. **Local path** on this machine (if not already remembered).
+
+Then: append the entry to `<TEAM_REPO>/knowledge/registry.json`, write a `repo-path-<repo>`
+memory, run `node "<TEAM_REPO>/knowledge.js" validate` (fix any error before continuing),
+and proceed. The `<fw>/apps/<repo>/` folder is created later by `capture` when the first
+doc is written — an empty knowledge set is fine; just note it.
+
+---
+
+### Claude Code Hooks Integration
+
+This repo has a `PostToolUse` hook configured in `.claude/settings.json` that
+**automatically runs `node knowledge.js validate`** whenever any knowledge file is
+written or edited. This means:
+
+- You do NOT need to run `validate` manually after a `capture` session write — you
+  will see validation results inline in the terminal as Claude writes each file.
+- If an error appears in the hook output (lines starting with `ERROR:`), the capture
+  step that caused it should be corrected before continuing.
+- The hook output is condensed: it shows only `ERROR`, `WARNING`, `OK`/`FAILED`
+  lines, so it does not flood the terminal.
+
+This hook is active whenever you have this repo open in Claude Code. It does not
+run in other project repos (it is scoped to the `claude` repo's `.claude/settings.json`).
+
+---
+
+### Before kickoff: should you run /session-resume first?
+
+If the developer says any of the following, suggest they run `/session-resume` **before**
+this kickoff to reload their prior session context:
+
+- "I'm continuing from yesterday"
+- "I'm picking up where I left off"
+- "I was in the middle of something"
+- "I saved my session last time"
+- Any mention of a prior unfinished feature or task
+
+In that case, say: "It sounds like you're continuing prior work. If you saved your
+session with `/session-save`, run `/session-resume latest` first — it will reload
+your exact state (what worked, what failed, and your next step) before we prime
+framework context with kickoff. This prevents you from re-trying approaches that
+already failed."
+
+If they have already run `/session-resume` and are now running `/kickoff`, proceed
+normally — the session context they loaded will complement the framework knowledge
+loaded here.

package/skills/php-patterns/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: php-patterns
+description: PHP pattern reference for TOGA Technology projects covering both frameworks. Framework 1.0 (App_ prefix), Framework 2.0 (_underscore prefix), PDO prepared statements, session handling, caching, api2 envelope format. Trigger when the user says "php-patterns", "show me the pattern for X", "how do I do X in 1.0/2.0", or starts writing new PHP code.
+---
+
+# PHP Patterns Skill
+
+Reference skill for TOGA Technology PHP patterns across both frameworks. Load this skill when writing new PHP code, reviewing patterns, or onboarding to a repo.
+
+## When to invoke
+
+- `/php-patterns` — general reference for both frameworks
+- `/php-patterns 1.0` — Framework 1.0 (App_) specific patterns
+- `/php-patterns 2.0` — Framework 2.0 (_underscore) specific patterns
+- `/php-patterns pdo` — PDO/database patterns
+- `/php-patterns queue` — queue/worker dispatch patterns
+- `/php-patterns api` — API response patterns
+
+---
+
+## Framework 1.0 (App_) Patterns
+
+### Controller structure
+
+```php
+<?php
+
+class App_Controller_Orders extends App_Controller {
+
+    public function indexAction(): void {
+        $model = App_Registry::get('Order');
+        $orders = $model->getAll(['user_id' => $this->auth->getUserId()]);
+        $this->view->assign('orders', $orders);
+        $this->view->render('orders/index');
+    }
+
+    public function createAction(): void {
+        if (!$this->request->isPost()) {
+            $this->response->error('Method not allowed', 405);
+            return;
+        }
+
+        $params = $this->request->post(['user_id', 'items', 'address_id']);
+
+        try {
+            $order = App_Registry::get('Order')->create($params);
+        } catch (App_Exception_Validation $e) {
+            $this->response->error($e->getMessage(), 400);
+            return;
+        }
+
+        $this->response->success(['order_id' => $order->id]);
+    }
+}
+```
+
+Key points:
+- Get models via `App_Registry::get('ModelName')` — never `new App_Model_*`
+- Filter request input explicitly: `$this->request->post(['key1', 'key2'])`
+- Return early on errors; happy path is last
+- Catch specific exception types, not bare `Exception`
+
+### Model structure
+
+```php
+<?php
+
+class App_Model_Order extends App_Model {
+
+    protected string $table = 'orders';
+
+    public function getByUser(int $userId): array {
+        if ($userId <= 0) {
+            return [];
+        }
+        return $this->db->select($this->table, ['user_id' => $userId]);
+    }
+
+    public function create(array $params): object {
+        $this->validate($params);  // throws App_Exception_Validation on failure
+        $id = $this->db->insert($this->table, [
+            'user_id'    => (int) $params['user_id'],
+            'address_id' => (int) $params['address_id'],
+            'status'     => 'pending',
+            'created_at' => date('Y-m-d H:i:s'),
+        ]);
+        return $this->db->find($this->table, $id);
+    }
+}
+```
+
+### Cron/scheduled task pattern (1.0)
+
+```php
+<?php
+// crons/ProcessPendingOrders.php
+
+class App_Cron_ProcessPendingOrders extends App_Cron {
+
+    public function run(): void {
+        $model = App_Registry::get('Order');
+        $pending = $model->getPending(100);  // always LIMIT — never unbounded
+
+        foreach ($pending as $order) {
+            try {
+                $model->process($order->id);
+            } catch (App_Exception_Processing $e) {
+                error_log('Cron: failed to process order ' . $order->id . ': ' . $e->getMessage());
+                // continue to next — do not let one failure abort the batch
+            }
+        }
+    }
+}
+```
+
+---
+
+## Framework 2.0 (_underscore) Patterns
+
+### Worker structure
+
+```php
+<?php
+
+class _Worker_ProcessOrder extends _Worker {
+
+    public function run(): void {
+        $orderId = (int) ($this->payload['order_id'] ?? 0);
+
+        if ($orderId <= 0) {
+            error_log('_Worker_ProcessOrder: missing order_id in payload');
+            return;  // discard — bad payload, no retry
+        }
+
+        try {
+            _Model_Order::process($orderId);
+        } catch (_Exception_OrderNotFound $e) {
+            error_log('_Worker_ProcessOrder: order not found: ' . $orderId);
+            return;  // discard
+        } catch (_Exception_Database $e) {
+            error_log('_Worker_ProcessOrder: DB error: ' . $e->getMessage());
+            throw $e;  // re-throw — queue will retry
+        }
+    }
+}
+```
+
+### Worker dispatch
+
+```php
+// Dispatch a single job
+_Queue::dispatch('_Worker_ProcessOrder', ['order_id' => $orderId]);
+
+// Dispatch with delay (seconds)
+_Queue::dispatch('_Worker_ProcessOrder', ['order_id' => $orderId], 30);
+
+// Dispatch to a specific queue name
+_Queue::dispatch('_Worker_ProcessOrder', $payload, 0, 'high-priority');
+```
+
+Never call `$worker->run()` or `new _Worker_ProcessOrder()` directly in application code.
+
+### API controller structure (api2)
+
+```php
+<?php
+
+class _Controller_Orders extends _Controller {
+
+    public function getAction(): array {
+        $orderId = (int) ($this->request->get('id') ?? 0);
+
+        if ($orderId <= 0) {
+            return ['success' => false, 'data' => null, 'errors' => ['Invalid order ID']];
+        }
+
+        $order = _Model_Order::find($orderId);
+
+        if ($order === null) {
+            return ['success' => false, 'data' => null, 'errors' => ['Order not found']];
+        }
+
+        return ['success' => true, 'data' => $order->toArray(), 'errors' => []];
+    }
+
+    public function createAction(): array {
+        $params = $this->request->post(['customer_id', 'items']);
+
+        try {
+            $order = _Model_Order::create($params);
+        } catch (_Exception_Validation $e) {
+            return ['success' => false, 'data' => null, 'errors' => $e->getErrors()];
+        }
+
+        return ['success' => true, 'data' => ['order_id' => $order->id], 'errors' => []];
+    }
+}
+```
+
+---
+
+## Cross-Framework Patterns
+
+### PDO prepared statements
+
+```php
+// SELECT with parameters
+$stmt = $pdo->prepare('SELECT * FROM orders WHERE user_id = ? AND status = ?');
+$stmt->execute([$userId, $status]);
+$orders = $stmt->fetchAll(PDO::FETCH_ASSOC);
+
+// INSERT
+$stmt = $pdo->prepare(
+    'INSERT INTO orders (user_id, status, created_at) VALUES (?, ?, ?)'
+);
+$stmt->execute([$userId, 'pending', date('Y-m-d H:i:s')]);
+$newId = $pdo->lastInsertId();
+
+// UPDATE with WHERE (always include WHERE — never unbounded UPDATE)
+$stmt = $pdo->prepare('UPDATE orders SET status = ? WHERE id = ?');
+$stmt->execute([$newStatus, $orderId]);
+
+// IN clause with variable number of params
+$ids = [1, 2, 3, 4];
+$placeholders = implode(',', array_fill(0, count($ids), '?'));
+$stmt = $pdo->prepare("SELECT * FROM orders WHERE id IN ($placeholders)");
+$stmt->execute($ids);
+```
+
+### Session handling
+
+```php
+// Start session safely
+if (session_status() === PHP_SESSION_NONE) {
+    session_start();
+}
+
+// Regenerate after login (prevents session fixation)
+session_regenerate_id(true);
+
+// Store only IDs in session — never full objects
+$_SESSION['user_id'] = $user->id;
+
+// Access session value safely
+$userId = (int) ($_SESSION['user_id'] ?? 0);
+```
+
+### Caching pattern
+
+```php
+// Check cache before hitting DB
+$cacheKey = 'user_profile_' . $userId;
+$profile = _Cache::get($cacheKey);
+
+if ($profile === null) {
+    $profile = _Model_User::getProfile($userId);
+    _Cache::set($cacheKey, $profile, 300);  // TTL in seconds
+}
+
+// Invalidate on write
+_Model_User::updateProfile($userId, $data);
+_Cache::delete('user_profile_' . $userId);
+```
+
+### Logging pattern
+
+```php
+// Log with context — never log sensitive fields
+error_log(sprintf(
+    '[%s] Order %d processing failed: %s',
+    date('Y-m-d H:i:s'),
+    $orderId,
+    $e->getMessage()
+));
+
+// Use log levels if the framework provides them
+_Log::error('Order processing failed', ['order_id' => $orderId, 'error' => $e->getMessage()]);
+// Do NOT include: passwords, tokens, card numbers, PII
+```
+
+### Input validation helper
+
+```php
+// Validate and sanitize common input types
+$id     = filter_input(INPUT_GET,  'id',     FILTER_VALIDATE_INT)   ?: 0;
+$email  = filter_input(INPUT_POST, 'email',  FILTER_VALIDATE_EMAIL) ?: '';
+$page   = filter_input(INPUT_GET,  'page',   FILTER_VALIDATE_INT,
+              ['options' => ['min_range' => 1, 'max_range' => 1000],
+               'flags'   => FILTER_NULL_ON_FAILURE]) ?? 1;
+
+// Allowlist for enum-like inputs
+$allowed_statuses = ['pending', 'processing', 'complete', 'cancelled'];
+$status = in_array($_GET['status'] ?? '', $allowed_statuses, true)
+    ? $_GET['status']
+    : 'pending';
+```