feat(workflow): build consolidation foundation from Pi's recovered design
- current-state.md -> v:1 schema (repairs Pi's destructive edit, restores decisions log) - recover Pi's workflow-consolidation design from session log into a durable doc - add drift-to-skill governance table - demote CLAUDE.md embedded state block to a pointer (stops harness re-injecting stale state) - new shared state-sync skill lives at ~/.claude/skills/state-sync (separate path) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Kisa
parent
93842438fa
commit
00cff7a5f8
4 changed files with 592 additions and 44 deletions
16
CLAUDE.md
16
CLAUDE.md
|
|
@ -10,21 +10,9 @@ worklist for supplier staff to prioritize outreach and capture revenue before it
|
|||
NOTE: Signal identifies gaps. It does not conduct outreach. Never write copy
|
||||
implying Signal contacts prescribers or patients directly.
|
||||
|
||||
## Current State (embedded — always in context)
|
||||
## Current State (deprecated — see `context/current-state.md`)
|
||||
|
||||
**ACTIVE:** Claude Code built Phase 2 (verified). Pi applied trust fixes, wrote Phase 4 spec, completed Shield competitor recon.
|
||||
**NEXT:** Pi designs Shield architecture (standalone compliance product). Claude Code on website review + whitepaper + Phase 2 verification.
|
||||
|
||||
**Open threads (at wrap-up):**
|
||||
|
||||
- LabABLE Meeting Fri 2026-06-26 1:30 PM — /pilot-prep (deferred).
|
||||
- Build Spec Phase 2 BUILT — auto-write + insight extraction in session brain. Pi verifies live write-path at next wrap-up.
|
||||
- Build Spec Phase 4 spec written by Pi (gen-api-ref.py + manual cross-ref). Ready for Claude Code build.
|
||||
- Shield architecture: Pi designing now. Competitor recon done (Dash ComplyOps, Vanta/Drata/Secureframe tiers).
|
||||
- 3 validation product blockers: MA misclassification, duplicate patient_id, doc-status override (Claude Code on these).
|
||||
|
||||
**At session START:** use this section for state. Then read `context/current-state.md` for the full shared state (decisions, stack details).
|
||||
**At WRAP-UP:** update this section AND `context/current-state.md` (keep both in sync).
|
||||
This block is deprecated to stop state drift. The active, canonical project state lives in **`context/current-state.md`** (schema `v:1`). Read and write it via the `state-sync` skill: at session start, `git pull --rebase` then read it; at wrap-up, update ACTIVE/NEXT, append one author-stamped decision, then commit + push. Do not keep rolling state in this file.
|
||||
|
||||
## Core Value Proposition
|
||||
|
||||
|
|
|
|||
|
|
@ -1,40 +1,34 @@
|
|||
v:1
|
||||
# current-state
|
||||
|
||||
ACTIVE: Readiness-model redesign locked + design brief written for Pi. Client supplies plan type (Signal never determines payer/eligibility/coverage); cite-the-basis; patient/CoverageLine/Shipment data model; required-vs-supplied verdict (no false green). cto-architect review folded in.
|
||||
NEXT (Pi, in order): (1) DESIGN the workflow consolidation from `docs/workflow-consolidation-brief-2026-06-23.md` — shared-state contract + reliable wrap-up commit/push hook + Claude/Pi skills+MCP parity + drift-to-skill governance + cleanup. Handed straight to Pi 2026-06-23; architect pass skipped per Kisa. (2) Produce the readiness-model build design from `docs/readiness-model-brief-2026-06-23.md`. Then Claude builds each (readiness sequence: rename coverage->readiness, rules-to-config, patient/line/shipment grouping + verdict, device-keyed override+recompute, require-plan-type + client mapping + remove guesser, frontend nesting). Pi RESOLVED rotating anonymous patient ID vs. persistent worklist via the RAP-ID/CSP-ID architecture.
|
||||
ACTIVE: Claude Code is implementing the workflow-consolidation build from Pi's recovered design. Live: this v:1 state schema, a shared `state-sync` skill, the demoted CLAUDE.md state block, and the drift-to-skill governance doc. Pending Kisa review: the auto-commit/push Stop hook (must be scoped to current-state.md, NOT `git add .`) and the global CLAUDE.md / Pi AGENTS.md startup edits.
|
||||
NEXT (agent, in order): (1) Claude: finish workflow-consolidation — scope + wire the Stop hook (current-state.md only), edit global CLAUDE.md + Pi AGENTS.md startup to pull+read current-state.md and drop redundant reads, decide MCP parity. (2) Claude: build the readiness model from Pi's design (rename coverage->readiness, rules-to-config, patient/line/shipment grouping + verdict, device-keyed override+recompute, require-plan-type + remove guesser, frontend nesting). (3) Claude: review Pi's AIOS + Automated Blog plans and recommend.
|
||||
|
||||
Pi has also refined strategic plans for a "Signal AIOS" for clients and an "Automated Blog" for the STTIL Solutions website, incorporating Granola call insights for API-first strategy, SEO tools, and agent orchestration.
|
||||
|
||||
## Decisions (last 7)
|
||||
|
||||
- 2026-06-23: Readiness model redesign. Signal never determines/guesses payer plan type, eligibility, or coverage; client supplies plan type as a required mapped field; every determination cites the rule + client input. Worklist = one record per patient UUID with per-device CoverageLines; verdict from required-vs-supplied (Clear to Ship earned by positive evidence, never by absent data). MA "bug" = delete the name-guesser. "coverage" code renamed to "readiness". Brief: docs/readiness-model-brief-2026-06-23.md. KG: plan_type_policy, scope_exclusion, determination_explainability.
|
||||
- 2026-06-23: RAP-ID/CSP-ID architectural solution proposed by Pi to reconcile rotating anonymous patient ID with persistent worklist tracking. Web App (SaaS Hosted by STTIL) is the recommended deployment model, with client-side management of Real Patient ID to CSP-ID mapping; HIPAA-compliant host like Validated Cloud is still required.
|
||||
- 2026-06-23: Shield architecture designed by Pi (standalone compliance product, tiered deployment, security, scalability, AI Consent Addendum focus). Ready for Claude Code build or further refinement.
|
||||
- 2026-06-23: DNSSEC verified live (DS propagated to public resolvers, ad flag set = chain validating). Website agent-files: staged compliance/factual fixes in local repo, NOT deployed: removed outreach wording, banned >25% stat, exposed pricing; fixed SWO term to Standard Written Order; refreshed learn-signal SKILL.md digest in agent-skills index. Prose rewrites + v0.2.0 field polish route to lead-content / deferred (agentskills.io schema URL unreachable).
|
||||
- 2026-06-23: Pi drafted strategic plans for "Signal AIOS" (productizing Shield's compliance architecture for Signal clients) and an "Automated Blog" for STTIL Solutions website (AI/SEO optimized, leveraging research agents and TriLane). These plans have been refined based on Granola call insights, emphasizing API-first strategy, specific SEO tools (AnswerThePublic, Schema.org), and agent orchestration concepts. Awaiting Claude Code's recommendations for implementation.
|
||||
- 2026-06-22: Phase 4 (support bot foundation) spec written by Pi — gen-api-ref.py + manual cross-reference. Ready for Claude Code build.
|
||||
- 2026-06-22: Build Spec Phase 2 built (Claude Code). navaigate-session-brain now auto-writes current-state.md (Step 3B) + extracts research insights to TriLane (Step 3C). Clerk prod migration COMPLETE (pk_live on Vercel + JWKS on Railway).
|
||||
## Decisions (last 8)
|
||||
- 2026-06-24 [CC]: Recovered Pi's workflow-consolidation design from its session log (Pi finalized it in chat but never wrote it to a file) to docs/workflow-consolidation-design-2026-06-24-pi-recovered.md. Built v:1 state schema + state-sync skill + governance doc; demoted CLAUDE.md embedded state block. Corrected Pi's Stop hook to scope to current-state.md, not `git add .`.
|
||||
- 2026-06-24 [Pi]: Workflow consolidation design completed (v:1 schema, read/write + commit/push protocol, Stop-hook automation, skills + MCP parity, drift-to-skill table, universal git versioning). Ready for Claude implementation.
|
||||
- 2026-06-23 [CC]: Workflow-consolidation brief handed to Pi (architect-reviewed); clean-start commit of current-state.md, context recovery artifacts gitignored, pushed to Forgejo + GitHub.
|
||||
- 2026-06-23 [CC]: Readiness model redesign locked. Signal never determines/guesses payer plan type, eligibility, or coverage; client supplies plan type as a required mapped field; every determination cites the rule + client input. Worklist = one record per patient UUID with per-device CoverageLines; verdict from required-vs-supplied. "coverage" renamed "readiness". Brief: docs/readiness-model-brief-2026-06-23.md.
|
||||
- 2026-06-23 [Pi]: RAP-ID/CSP-ID architecture proposed to reconcile rotating anonymous patient ID with persistent worklist. SaaS web app hosted by STTIL; client holds Real-ID to CSP-ID map; HIPAA host (Validated Cloud) still required.
|
||||
- 2026-06-23 [Pi]: Shield architecture designed (standalone compliance product, tiered deployment, AI Consent Addendum). Ready for Claude build or refinement.
|
||||
- 2026-06-23 [CC]: DNSSEC verified live. Website agent-file compliance fixes staged locally (removed outreach wording, banned >25% stat, exposed pricing, SWO term fixed) — NOT deployed; prose rewrites routed to lead-content.
|
||||
- 2026-06-22 [CC]: Build Spec Phase 2 built; Clerk prod migration complete (pk_live on Vercel + JWKS on Railway). Phase 4 (support bot foundation) spec by Pi ready for build.
|
||||
|
||||
## Open Threads (max 5)
|
||||
|
||||
- READINESS MODEL REDESIGN (2026-06-23): design brief for Pi at `docs/readiness-model-brief-2026-06-23.md` (folds in cto-architect review). Pi produces the build design; then Claude builds. Supersedes the piecemeal 3-blockers framing. KG added: plan_type_policy, scope_exclusion, determination_explainability.
|
||||
- SIGNAL AIOS & AUTOMATED BLOG STRATEGIC PLANS (2026-06-23): Pi has refined these plans based on Granola call insights. Claude Code to review and make recommendations for moving forward.
|
||||
- LabABLE Meeting Fri 2026-06-26 1:30 PM — /pilot-prep (deferred).
|
||||
- Website copy: brief lead-content for human-page rewrites (extract "eligibility"/"coverage" language, stat consistency), run copy-review, then commit + deploy the staged agent-file fixes. Retention 6-year doc fix (2 stale "7 year" lines). BAA privacy wording attorney-gated.
|
||||
- Build Spec Phase 4 (support bot foundation) spec by Pi - ready for Claude Code build.
|
||||
- WORKFLOW CONSOLIDATION (2026-06-24): building from Pi's recovered design. Remaining: Stop hook (Kisa review), global CLAUDE.md + Pi AGENTS.md startup edits, MCP parity, optional skills-as-git-repo. Design: docs/workflow-consolidation-design-2026-06-24-pi-recovered.md; brief: docs/workflow-consolidation-brief-2026-06-23.md.
|
||||
- READINESS MODEL BUILD (2026-06-23): Pi's build design ready; Claude builds the rename + rules-to-config + grouping/verdict sequence. Brief: docs/readiness-model-brief-2026-06-23.md.
|
||||
- SIGNAL AIOS & AUTOMATED BLOG PLANS (2026-06-23): Pi refined with Granola insights; Claude to review and recommend.
|
||||
- LabABLE Meeting Fri 2026-06-26 1:30 PM — /pilot-prep.
|
||||
- Website copy: brief lead-content for human-page rewrites (extract eligibility/coverage language); deploy staged agent-file fixes; 6-year retention doc fix. BAA wording attorney-gated.
|
||||
|
||||
## Stack
|
||||
|
||||
- Signal: PHI contained in `patient_id` field (name, MRN, account #s) — requires tokenization via proposed RAP-ID/CSP-ID architecture (2026-06-23 call: rotating anonymous ID, not static UUID; PROBLEM RESOLVED BY PI).
|
||||
- Model for Pi: `deepseek/deepseek-v4-flash` (cheap, high-thinking). Subagents also default to this model.
|
||||
- Signal-api: Railway (signal-api-production-91c2)
|
||||
- Signal-ui: Vercel (signal-ui-xi.vercel.app)
|
||||
- Supabase: itmospnregdyiatbbdwl (JWT key)
|
||||
- TriLane: localhost:8000 (signal/sessions/scale-software workspaces). Non-MCP agents (Pi) reach it over HTTP at `127.0.0.1:8000` — full contract (search via branch-scoped retrieval, memory read/write, live branch ids) in `trilane/TRILANE_HTTP_API.md`. Verified live 2026-06-23.
|
||||
- Clerk: production key deployed to Vercel + Railway. Frontend auth via `clerk.sttilsolutions.com` (verified). Google OAuth configured.
|
||||
- Signal: PHI contained in `patient_id` (name, MRN, account #s) — tokenization via RAP-ID/CSP-ID (rotating anonymous ID, not static UUID).
|
||||
- Signal-api: Railway (signal-api-production-91c2). Signal-ui: Vercel (signal-ui-xi.vercel.app). Supabase: itmospnregdyiatbbdwl (JWT key).
|
||||
- Clerk: production key on Vercel + Railway; frontend auth via clerk.sttilsolutions.com; Google OAuth configured.
|
||||
- TriLane: localhost:8000 (signal/sessions/scale-software). Pi reaches it over HTTP (127.0.0.1:8000); contract in trilane/TRILANE_HTTP_API.md.
|
||||
- Model for Pi: deepseek/deepseek-v4-flash.
|
||||
|
||||
## Tip
|
||||
State protocol: read = `git pull --rebase` then read this file (warn if Updated > 24h old); write = edit ACTIVE/NEXT, append one author-stamped decision, then commit + push. Full protocol in the `state-sync` skill. TriLane = searchable archive, not live state.
|
||||
|
||||
TriLane Memory has the `research_insight` category live in the Signal workspace. Session summaries live in the Sessions workspace (auto-flow), not Signal. Meeting/Granola notes also land in the Sessions workspace; Pi can query them over HTTP.
|
||||
|
||||
## Updated: 2026-06-23 (Claude Code + Kisa: diagnosed why current-state.md was missed at startup — the global Session Protocol never pointed to it; designed the shared-state + workflow-consolidation cleanup with a cto-architect pressure-test; committed clean-start current-state.md, gitignored context recovery artifacts, pushed to Forgejo + GitHub; wrote and handed the consolidated brief to Pi at docs/workflow-consolidation-brief-2026-06-23.md (straight to Pi, architect pass skipped per Kisa). NEXT: Pi designs the workflow consolidation, then the readiness-model build.)
|
||||
## Updated: 2026-06-24 (CC: recovered Pi's workflow-consolidation design from its session log and built the foundation — v:1 schema, state-sync skill, governance doc, demoted CLAUDE.md state block. Pending Kisa review: scoped Stop hook + global startup edits. NEXT: finish consolidation, then readiness-model build.)
|
||||
|
|
|
|||
25
docs/drift-to-skill-governance-2026-06-24.md
Normal file
25
docs/drift-to-skill-governance-2026-06-24.md
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
# Drift-to-Skill Governance
|
||||
|
||||
**Date:** 2026-06-24 · **Source:** Pi workflow-consolidation design (recovered) + architect-reviewed brief.
|
||||
|
||||
**Principle:** Anywhere a recurring protocol relies on a human remembering, it drifts. The fix is a **skill** (for on-demand, judgment-bearing work) or a **hook** (for automatic, no-trigger work), never a standing reminder. Manual stays manual only on purpose.
|
||||
|
||||
## Decision table
|
||||
|
||||
| Manual protocol | Current behavior | Recommended automation | Type | Build by | Notes |
|
||||
|---|---|---|---|---|---|
|
||||
| Session-start git pulls | Manual `git pull` + read per repo | Automated read protocol | Hook | Pi / Claude | Applies to `signal` and `~/.claude/skills` (if separate repo). |
|
||||
| Session wrap-up commit/push | Manual edit/commit/push (session-brain Step 5) | Automated write protocol | Hook | Pi / Claude | **Scope to `current-state.md`, not `git add .`** (safety correction to Pi's draft). |
|
||||
| Git commit + push (general) | Manual `git add/commit/push` | Skill | Skill | Claude | Existing `git-push` skill for broader work. |
|
||||
| Content calendar update (NocoDB) | Manual curl/GUI | Skill | Skill | Pi / Claude | "Update NocoDB content calendar". |
|
||||
| KG / TriLane queries | Manual MCP / HTTP curl | Skill | Skill | Pi / Claude | "Query TriLane" over the documented HTTP API. |
|
||||
| current-state.md staleness check | Manual read of `Updated:` | Automated read protocol | Hook | Pi / Claude | Part of the read protocol. |
|
||||
| MCP server sync | Manual per-agent config | Automated MCP parity | Hook | Pi / Claude | Reads a shared MCP config at startup. |
|
||||
| New policy / regulatory doc | Manual creation | Skill | Skill | Pi / Claude | Drafts + commits the doc. |
|
||||
| Blog post creation/update | Manual | Skill pipeline | Workflow | Pi / Claude | Automated blog pipeline (see Automated Blog plan). |
|
||||
|
||||
## Build order (risk-ascending)
|
||||
|
||||
1. **Done:** v:1 state schema, `state-sync` skill, demoted CLAUDE.md state block, this governance doc.
|
||||
2. **Pending Kisa review (high blast radius):** scoped commit/push Stop hook; global CLAUDE.md + Pi `AGENTS.md` startup edits; MCP parity.
|
||||
3. **Later:** skills-as-git-repo, the per-protocol skills above (NocoDB, TriLane query, policy/blog), as each is needed.
|
||||
541
docs/workflow-consolidation-design-2026-06-24-pi-recovered.md
Normal file
541
docs/workflow-consolidation-design-2026-06-24-pi-recovered.md
Normal file
|
|
@ -0,0 +1,541 @@
|
|||
# Workflow Consolidation — Pi Design (RECOVERED from Pi session log 2026-06-24)
|
||||
|
||||
> Recovered by Claude Code from `~/.pi/agent/sessions/...019ef117...jsonl` because Pi finalized this
|
||||
> design only in its conversation and never wrote it to a file. This file is the durable artifact.
|
||||
> Reconcile against the architect-reviewed brief `workflow-consolidation-brief-2026-06-23.md` before building.
|
||||
|
||||
---
|
||||
|
||||
Okay, I understand. The plan is to:
|
||||
|
||||
1. **Integrate the "golden nuggets"** regarding expanded Git version control into the workflow consolidation design document.
|
||||
2. **Confirm the updated design is final.**
|
||||
3. **Prepare for session wrap-up by updating `current-state.md`** with the final design details and clear next steps for Claude Code.
|
||||
|
||||
---
|
||||
|
||||
## **Revised Design Document: Workflow Consolidation for STTIL Agents**
|
||||
|
||||
**Date:** 2026-06-24 (Revised)
|
||||
**Purpose:** To eliminate workflow drift, centralize state management, and automate recurring manual protocols across Pi and Claude Code agents operating within STTIL Solutions, leveraging Git as a universal version control system.
|
||||
|
||||
---
|
||||
|
||||
### **1. The State Contract: `current-state.md` Schema & Protocol**
|
||||
|
||||
This section defines the canonical format and interaction protocols for the `current-state.md` file, the single source of truth for volatile project state within a repository.
|
||||
|
||||
**A. `current-state.md` Schema (Schema `v:1`)**
|
||||
|
||||
```markdown
|
||||
v:1
|
||||
# current-state
|
||||
|
||||
ACTIVE: [Concise summary of what is actively being worked on by either agent. Limit to 1-2 sentences.]
|
||||
NEXT (Agent, in order): [Ordered list of next tasks. Each task should specify the responsible agent (Pi/Claude) and a brief description. E.g., (1) Claude: Build Phase 2. (2) Pi: Design X. ]
|
||||
|
||||
## Decisions (last X)
|
||||
- [YYYY-MM-DD]: [Decision summary. Include author tag: [Pi] or [CC]. E.g., - 2026-06-24: Decision A made. [Pi]]
|
||||
- [YYYY-MM-DD]: [Decision summary. Include author tag: [Pi] or [CC].]
|
||||
|
||||
## Open Threads (max 5)
|
||||
- [Concise summary of an open, unresolved issue or pending task, with context. E.g., - Need to contact Validated Cloud for pricing (deferred until Pi contact). ]
|
||||
- [Concise summary of an open, unresolved issue or pending task, with context.]
|
||||
|
||||
## Stack
|
||||
- [Key infrastructure components, models, and tools used by the project. Updates infrequently. E.g., - Signal: Patient IDs now use RAP-ID/CSP-ID architecture.]
|
||||
- [Key infrastructure components, models, and tools used by the project.]
|
||||
|
||||
## Tip
|
||||
- [General advice or reminder relevant to the current project context. E.g., - TriLane Memory is reachable via HTTP not MCP for Pi.]
|
||||
|
||||
## Updated: [YYYY-MM-DD] [Brief overall project status/changelog. Include responsible agents. E.g., Updated: 2026-06-24 (Pi: Workflow consolidation design complete; Claude: Built X.)]
|
||||
```
|
||||
|
||||
**B. De-duplication Map (Source of Truth for Information Types)**
|
||||
|
||||
* **`current-state.md`:** Volatile project state (changes every session) – ACTIVE/NEXT tasks, recent decisions, immediate open threads.
|
||||
* **`CLAUDE.md`:** Stable project facts (true for months) – What the product is, core PHI rules, run commands, permanent checklists, core technical stack. Demoted, one-line "Current State" pointer.
|
||||
* **Claude Memory:** Kisa/CC operating notes, internal thought processes, temporary working notes.
|
||||
* **TriLane (Searchable Archive & Intelligence Hub):** History, validated research insights, long-term learning, previous session summaries, **correlated market projections**. TriLane *consumes* Git-managed versioned artifacts as input for its intelligence.
|
||||
|
||||
**C. Read Protocol (Agent Startup/Resume)**
|
||||
|
||||
1. **`git pull --rebase origin <current_branch>`:** Fetch latest changes and rebase local branch to ensure working on the freshest state for the primary repository.
|
||||
2. **`git pull --rebase origin <skills_repo_branch>`:** If skills are in a separate Git repo, update them.
|
||||
3. **Read `signal/context/current-state.md`:** Load file contents into agent's short-term context.
|
||||
4. **Surface Staleness Signal:** Compare current date to the `Updated:` timestamp in `current-state.md`. If `current-state.md` is older than 24 hours, issue a warning to the user: "Warning: Project state last updated X days ago. Consider reviewing recent activity." *Constraint: Lean, token-conscious – this is a simple check, not a deep diff.*
|
||||
|
||||
**D. Write Protocol (Agent Wrap-up/Commit)**
|
||||
|
||||
1. **Single Mutable Head:** Agents may only directly modify the `ACTIVE` and `NEXT` sections.
|
||||
2. **Append-Only Decisions Log:** All new decisions must be appended to the `Decisions` section, prefixed with `[YYYY-MM-DD]: [Decision Summary. [Author Tag]]`.
|
||||
3. **Update `Updated:` Timestamp:** The `Updated:` line at the bottom must be updated to the current date and a brief status summary.
|
||||
4. **Rebase-and-Commit Cycle (General for any Git-managed file):**
|
||||
* Immediately before writing to *any* Git-managed file (e.g., `current-state.md`, `SKILL.md`, `payer_rules.json`, blog posts), execute `git pull --rebase origin <current_branch>`.
|
||||
* If a conflict occurs, the *last writer hand-merges* their changes. (`-X ours` and lock files are forbidden).
|
||||
* Write changes to the file(s).
|
||||
* `git add <path/to/modified/file(s)>`.
|
||||
* `git commit -m "Update [file(s)] by [Author Tag]: [brief summary of changes]"`
|
||||
* `git push origin <current_branch>`.
|
||||
5. **Visibility for Push Failures:** Push failures must be reported directly to the console/session output, never swallowed silently.
|
||||
|
||||
---
|
||||
|
||||
### **2. Reliable Wrap-up Commit + Push (Automation Design)**
|
||||
|
||||
To prevent state loss due to crashes or skipped wrap-ups.
|
||||
|
||||
**A. Recommended Mechanism: Harness Stop Hook**
|
||||
|
||||
The primary mechanism will be a harness-level stop hook, which executes reliable git operations regardless of user-triggered wrap-up or session termination.
|
||||
|
||||
* **Placement:**
|
||||
* **Pi:** `~/.pi/agent/settings.json` (or equivalent harness configuration).
|
||||
* **Claude Code:** `~/.claude/agent/settings.json` (or equivalent harness configuration).
|
||||
* **Action:** Execute a script (e.g., `update_repo_on_stop.sh`) when the agent session stops. This script will generalize the `current-state.md` logic to any modified file within the working repository.
|
||||
* **`update_repo_on_stop.sh` Script Logic (Conceptual):**
|
||||
```bash
|
||||
#!/bin/bash
|
||||
PRIMARY_REPO_ROOT="/Users/sttil-solutions/projects/signal" # Target the main project repo
|
||||
|
||||
# --- Generic Git Auto-Commit & Push Logic ---
|
||||
# This script is a generalized abstraction. Actual implementation needs to identify
|
||||
# which Git repositories are active (e.g., "$PRIMARY_REPO_ROOT", "~/.claude/skills/")
|
||||
# and perform operations for each.
|
||||
|
||||
handle_repo() {
|
||||
local repo_path=$1
|
||||
local branch_name="main" # Or dynamically determine current branch
|
||||
cd "$repo_path" || { echo "ERROR: Could not change directory to $repo_path" >&2; return 1; }
|
||||
|
||||
if git diff --quiet || git diff --cached --quiet; then
|
||||
echo "Repository $repo_path is clean, no auto-commit needed."
|
||||
return 0
|
||||
fi
|
||||
|
||||
echo "Pending changes detected in $repo_path. Attempting auto-commit/push."
|
||||
|
||||
# Stage all changes that are not untracked
|
||||
git add .
|
||||
|
||||
# Attempt to commit
|
||||
local commit_message="Auto-commit pending changes via stop hook. [$(hostname)]"
|
||||
if ! git commit -m "$commit_message"; then
|
||||
echo "WARNING: Failed to auto-commit changes in $repo_path. May be due to other unstaged/untracked files or a dirty index for some files." >&2
|
||||
echo "Please inspect manually: cd $repo_path && git status" >&2
|
||||
# Stash if necessary to clean working directory, but don't lose changes
|
||||
# if ! git diff --quiet; then
|
||||
# echo "Attempting to stash remaining uncommitted changes." >&2
|
||||
# git stash push --message "Auto-stashed by stop hook: $repo_path" >&2
|
||||
# fi
|
||||
return 1 # Indicate failure
|
||||
fi
|
||||
|
||||
# Pull and rebase before push
|
||||
if ! git pull --rebase origin "$branch_name"; then
|
||||
echo "WARNING: Auto-push failed for $repo_path due to rebase conflict. Please resolve manually: cd $repo_path && git status" >&2
|
||||
return 1
|
||||
fi
|
||||
|
||||
# Push
|
||||
if ! git push origin "$branch_name"; then
|
||||
echo "WARNING: Auto-push failed for $repo_path. Please push manually: cd $repo_path && git push" >&2
|
||||
return 1
|
||||
fi
|
||||
echo "Successfully auto-committed and pushed pending changes in $repo_path."
|
||||
return 0
|
||||
}
|
||||
|
||||
# Handle primary project repo
|
||||
handle_repo "$PRIMARY_REPO_ROOT"
|
||||
|
||||
# Handle skills repo if it's a separate Git repo (e.g., "~/.claude/skills/")
|
||||
# SKILLS_REPO_ROOT="~/.claude/skills" # This path needs to be absolute and correctly resolved by the shell
|
||||
# handle_repo "$SKILLS_REPO_ROOT"
|
||||
```
|
||||
* **Push Failure Visibility:** The script above ensures push failures are explicitly echoed to `stderr`, making them visible in the agent's log/terminal history.
|
||||
* **Session-Brain Step 5:** The `navaigate-session-brain` Step 5 remains the rich, user-triggered wrap-up path, offering more control and context.
|
||||
|
||||
---
|
||||
|
||||
### **3. Skills + MCP Parity (Claude ↔ Pi)**
|
||||
|
||||
**A. Skills Parity**
|
||||
|
||||
* **Shared Directory:** `~/.claude/skills/` remains the single, shared skill library.
|
||||
* **Skills Version Control:** `~/.claude/skills/` will itself be a Git repository (e.g., cloned from `forgejo.sttilsolutions.com/sttil-platform/sttil-skills.git`). This ensures all skills are version-controlled, traceable, and synchronized across agents via `git pull` at startup.
|
||||
* **`~/.pi/agent/AGENTS.md` Update:**
|
||||
* **Existing Text (to be replaced):** The hand-maintained table mapping skill names to files.
|
||||
* **New Text:** Replace the table with a declarative statement and a guide for skill discovery.
|
||||
```markdown
|
||||
# Available Skills
|
||||
|
||||
Pi and Claude Code share a unified, version-controlled skill library located at `~/.claude/skills/` (a Git repository automatically updated at session startup).
|
||||
To use a skill, invoke it by its name after loading its respective `SKILL.md` file.
|
||||
|
||||
**Skill Discovery:** To see available skills, consult the contents of `~/.claude/skills/` which is the Git repository cloned from `forgejo.sttilsolutions.com/sttil-platform/sttil-skills.git`.
|
||||
```
|
||||
|
||||
**B. MCP Parity (Common Server Configuration)**
|
||||
|
||||
* **Shared MCP Configuration File:** Introduce a git-versioned plain-text file (e.g., `signal/context/shared_mcp_config.json`) within the `signal` repo. This file will define common MCP server connections (e.g., `trilane`).
|
||||
* **Harness Load Hook:** Implement a lightweight hook in both Pi and Claude Code's harness configurations that executes on startup/connect:
|
||||
* Reads `signal/context/shared_mcp_config.json`.
|
||||
* Dynamically registers or updates their respective `mcp.json` or in-memory MCP server list.
|
||||
* **Non-Shared MCPs:** `graphify` and `use-railway` will continue to be configured directly within Claude Code's specific `mcp.json` as needed, outside the shared file.
|
||||
|
||||
---
|
||||
|
||||
### **4. Drift-to-Skill Governance (Decision Table)**
|
||||
|
||||
This table categorizes recurring manual activities and recommends their automation strategy.
|
||||
|
||||
| Manual Protocol | Current Behavior | Recommended Automation | Type | Build By (Agent) | Notes |
|
||||
| :------------------------------------ | :---------------------------------------------------- | :----------------------- | :------------ | :--------------- | :------------------------------------------------------------------------------------------------------- |
|
||||
| Session Start Git Pulls | Manual `git pull`, `read` command (per repo) | **Automated Read Protocol** | Hook | Pi / Claude | Applies to `signal` repo and `~/.claude/skills` repo (if separate). |
|
||||
| Session Wrap-up Auto-commit/push | Manual `edit`, `commit`, `push` (`navaigate-session-brain` Step 5) | **Automated Write Protocol** | Hook | Pi / Claude | Generalized to auto-commit/push all changes in managed Git repos. |
|
||||
| Git Commit + Push (general) | Manual `git add`, `commit`, `push` | **Skill** | Skill | Claude | A general `/git-push` skill for other work. |
|
||||
| Content Calendar Update (NocoDB) | Manual curl/GUI update | **Skill** | Skill | Pi / Claude | "Update NocoDB content calendar" skill (might use `mcp` if NocoDB is an MCP server). |
|
||||
| KG Queries (TriLane) | Manual TriLane `mcp` calls (now HTTP `curl`) | **Skill** | Skill | Pi / Claude | "Query TriLane" skill (e.g., `/trilane-query`), using the documented HTTP API. |
|
||||
| `current-state.md` Staleness Check | Manual check of `Updated:` timestamp | **Automated Read Protocol** | Hook | Pi / Claude | Defined in Section 1.C. |
|
||||
| MCP Server Sync | Manual `mcp connect` for each agent | **Automated MCP Parity** | Hook | Pi / Claude | Reads `shared_mcp_config.json` at startup. |
|
||||
| New Policy/Doc (e.g., regulatory summary) | Manual creation/updates | **Skill** | Skill | Pi / Claude | Skill to draft/update documents (e.g., `/write-policy`, `/summarize-regulation`), committing changes. |
|
||||
| Blog Post Creation/Update | Manual | **Skill Pipeline** | Workflow | Pi / Claude | Automated blog content pipeline, committing posts to blog repo (see Automated Blog Plan). |
|
||||
|
||||
---
|
||||
|
||||
### **5. Cleanup / Smoother Workflow**
|
||||
|
||||
This outlines the broader housekeeping changes for coherent start/wrap protocols.
|
||||
|
||||
* **Retire `project_next_steps.md`:** This file will no longer be maintained as its purpose is entirely superseded by the `NEXT` section of `current-state.md`. Claude's internal memory should be updated to no longer reference/expect this file.
|
||||
* **Demote Embedded "Current State" in `CLAUDE.md`:**
|
||||
* **Existing Text (in `signal/CLAUDE.md`):**
|
||||
```markdown
|
||||
## Current State (embedded — always in context)
|
||||
**ACTIVE:** Claude Code built Phase 2 (verified). Pi applied trust fixes, wrote Phase 4 spec, completed Shield competitor recon.
|
||||
**NEXT:** Pi designs Shield architecture (standalone compliance product). Claude Code on website review + whitepaper + Phase 2 verification.
|
||||
... (rolling fields) ...
|
||||
**At session START:** use this section for state. Then read `context/current-state.md` for the full shared state (decisions, stack details).
|
||||
**At WRAP-UP:** update this section AND `context/current-state.md` (keep both in sync).
|
||||
```
|
||||
* **New Text (`signal/CLAUDE.md` startup edit):**
|
||||
```markdown
|
||||
## Current State (deprecated — see `context/current-state.md`)
|
||||
**Purpose:** This block is deprecated due to state drift. For the active, canonical project state, always refer to `signal/context/current-state.md`.
|
||||
```
|
||||
* **Implication:** This ensures the harness auto-injects a trivial string for `CLAUDE.md`'s "Current State" reducing token usage and eliminating confusion.
|
||||
* **Coherent Start/Wrap Protocol:** The combined read/write protocols (Section 1.C, 1.D, 2.A) form a unified process for both Pi and Claude.
|
||||
* **`current-state.md` per Repo:** This design explicitly maintains `context/current-state.md` within the `signal` repo, reinforcing the principle of one state file per logical project repository where agents are active.
|
||||
|
||||
---
|
||||
|
||||
### **Universal Git Version Control (Golden Nugget Integration)**
|
||||
|
||||
This overarching principle applies across all workstreams:
|
||||
|
||||
**Principle:** **All human-readable, agent-readable, and machine-actionable artifacts that constitute stable project knowledge, configuration, active state, or output should be managed under Git version control.**
|
||||
|
||||
* **Skills (`~/.claude/skills/`):** Should be a dedicated Git repository. Changes to skills are versioned, traceable, and synchronized via `git pull --rebase` at agent startup.
|
||||
* **Internal Policies & Operational Documentation (`docs/compliance/`, etc.):** Critical for auditability and consistency. All such documents (e.g., privacy policies, data-handling procedures, API contracts) must be versioned in Git. Agents (or humans) draft changes, commit, and push.
|
||||
* **External Regulatory Summaries & Payer Rule Interpretations (`docs/regulatory_summaries/`, `payer_rules.json`):** Git provides a precise, auditable history of when these interpretations changed, crucial for compliance logic (`Signal` and `Shield`). When a research agent flags an external change, its *processed interpretation* and any derived rule updates are committed to Git with clear commit messages and timestamps.
|
||||
* **Automated Blog Content:** Each blog post's content (e.g., Markdown files) and associated metadata (e.g., Schema.org JSON-LD) are versioned in Git. Git pushes can automatically trigger publication via CI/CD.
|
||||
* **TriLane as Intelligence Layer:** Git-versioned artifacts serve as concrete, traceable inputs for TriLane. A commit hash can be a direct citation for a `research_insight` in TriLane. TriLane *correlates* these versioned inputs to produce higher-level market projections and strategic guidance, which can then be used by agents to draft blog posts or update other Git-managed documents. This creates a powerful feedback loop where Git provides the auditable granular changes, and TriLane provides the strategic macro-level insights.
|
||||
|
||||
This enhancement ensures a robust, trustworthy, and self-maintaining flow of information and work across the entire STTIL Solutions agent ecosystem.
|
||||
|
||||
---
|
||||
|
||||
### **Deliverable Summary**
|
||||
|
||||
This revised design document provides:
|
||||
|
||||
1. **`current-state.md` Schema (`v:1`) and Template:** (Section 1.A)
|
||||
2. **Read/Write Protocol Steps:** (Section 1.C, 1.D) ready for inclusion in shared skill startup/wrap-up logic.
|
||||
3. **De-duplication Map:** (Section 1.B)
|
||||
4. **Recommended Wrap-up Automation (Harness Stop Hook):** (Section 2.A) including conceptualized `update_repo_on_stop.sh` script logic and placement.
|
||||
5. **Skills/MCP Parity Fixes:** (Section 3) with exact proposed edits for `~/.pi/agent/AGENTS.md` and mechanism for `shared_mcp_config.json`.
|
||||
6. **Drift-to-Skill Decision Table:** (Section 4)
|
||||
7. **Exact Startup Edits for `CLAUDE.md`:** (Section 5)
|
||||
8. **Golden Nugget Integration:** Explicitly details the **Universal Git Version Control** strategy across all relevant artifact types, solidifying the foundation for STTIL Solutions' agent-driven workflow.
|
||||
|
||||
This comprehensive and now finalized design is ready for Claude Code's implementation phase.
|
||||
|
||||
---
|
||||
|
||||
**Next: Session Brain Update (Wrap-up)**
|
||||
|
||||
I will now update `current-state.md` to reflect the completion and finalization of this workflow consolidation design, providing clear next steps for Claude Code to implement it. This will also mark the end of this session.Okay, I understand. The plan is to:
|
||||
|
||||
1. **Integrate the "golden nuggets"** regarding expanded Git version control into the workflow consolidation design document.
|
||||
2. **Confirm the updated design is final.**
|
||||
3. **Prepare for session wrap-up by updating `current-state.md`** with the final design details and clear next steps for Claude Code.
|
||||
|
||||
---
|
||||
|
||||
## **Revised Design Document: Workflow Consolidation for STTIL Agents**
|
||||
|
||||
**Date:** 2026-06-24 (Revised)
|
||||
**Purpose:** To eliminate workflow drift, centralize state management, and automate recurring manual protocols across Pi and Claude Code agents operating within STTIL Solutions, leveraging Git as a universal version control system.
|
||||
|
||||
---
|
||||
|
||||
### **1. The State Contract: `current-state.md` Schema & Protocol**
|
||||
|
||||
This section defines the canonical format and interaction protocols for the `current-state.md` file, the single source of truth for volatile project state within a repository.
|
||||
|
||||
**A. `current-state.md` Schema (Schema `v:1`)**
|
||||
|
||||
```markdown
|
||||
v:1
|
||||
# current-state
|
||||
|
||||
ACTIVE: [Concise summary of what is actively being worked on by either agent. Limit to 1-2 sentences.]
|
||||
NEXT (Agent, in order): [Ordered list of next tasks. Each task should specify the responsible agent (Pi/Claude) and a brief description. E.g., (1) Claude: Build Phase 2. (2) Pi: Design X. ]
|
||||
|
||||
## Decisions (last X)
|
||||
- [YYYY-MM-DD]: [Decision summary. Include author tag: [Pi] or [CC]. E.g., - 2026-06-24: Decision A made. [Pi]]
|
||||
- [YYYY-MM-DD]: [Decision summary. Include author tag: [Pi] or [CC].]
|
||||
|
||||
## Open Threads (max 5)
|
||||
- [Concise summary of an open, unresolved issue or pending task, with context. E.g., - Need to contact Validated Cloud for pricing (deferred until Pi contact). ]
|
||||
- [Concise summary of an open, unresolved issue or pending task, with context.]
|
||||
|
||||
## Stack
|
||||
- [Key infrastructure components, models, and tools used by the project. Updates infrequently. E.g., - Signal: Patient IDs now use RAP-ID/CSP-ID architecture.]
|
||||
- [Key infrastructure components, models, and tools used by the project.]
|
||||
|
||||
## Tip
|
||||
- [General advice or reminder relevant to the current project context. E.g., - TriLane Memory is reachable via HTTP not MCP for Pi.]
|
||||
|
||||
## Updated: [YYYY-MM-DD] [Brief overall project status/changelog. Include responsible agents. E.g., Updated: 2026-06-24 (Pi: Workflow consolidation design complete; Claude: Built X.)]
|
||||
```
|
||||
|
||||
**B. De-duplication Map (Source of Truth for Information Types)**
|
||||
|
||||
* **`current-state.md`:** Volatile project state (changes every session) – ACTIVE/NEXT tasks, recent decisions, immediate open threads.
|
||||
* **`CLAUDE.md`:** Stable project facts (true for months) – What the product is, core PHI rules, run commands, permanent checklists, core technical stack. Demoted, one-line "Current State" pointer.
|
||||
* **Claude Memory:** Kisa/CC operating notes, internal thought processes, temporary working notes.
|
||||
* **TriLane (Searchable Archive & Intelligence Hub):** History, validated research insights, long-term learning, previous session summaries, **correlated market projections**. TriLane *consumes* Git-managed versioned artifacts as input for its intelligence.
|
||||
|
||||
**C. Read Protocol (Agent Startup/Resume)**
|
||||
|
||||
1. **`git pull --rebase origin <current_branch>`:** Fetch latest changes and rebase local branch to ensure working on the freshest state for the primary repository.
|
||||
2. **`git pull --rebase origin <skills_repo_branch>`:** If skills are in a separate Git repo, update them.
|
||||
3. **Read `signal/context/current-state.md`:** Load file contents into agent's short-term context.
|
||||
4. **Surface Staleness Signal:** Compare current date to the `Updated:` timestamp in `current-state.md`. If `current-state.md` is older than 24 hours, issue a warning to the user: "Warning: Project state last updated X days ago. Consider reviewing recent activity." *Constraint: Lean, token-conscious – this is a simple check, not a deep diff.*
|
||||
|
||||
**D. Write Protocol (Agent Wrap-up/Commit)**
|
||||
|
||||
1. **Single Mutable Head:** Agents may only directly modify the `ACTIVE` and `NEXT` sections.
|
||||
2. **Append-Only Decisions Log:** All new decisions must be appended to the `Decisions` section, prefixed with `[YYYY-MM-DD]: [Decision Summary. [Author Tag]]`.
|
||||
3. **Update `Updated:` Timestamp:** The `Updated:` line at the bottom must be updated to the current date and a brief status summary.
|
||||
4. **Rebase-and-Commit Cycle (General for any Git-managed file):**
|
||||
* Immediately before writing to *any* Git-managed file (e.g., `current-state.md`, `SKILL.md`, `payer_rules.json`, blog posts), execute `git pull --rebase origin <current_branch>`.
|
||||
* If a conflict occurs, the *last writer hand-merges* their changes. (`-X ours` and lock files are forbidden).
|
||||
* Write changes to the file(s).
|
||||
* `git add <path/to/modified/file(s)>`.
|
||||
* `git commit -m "Update [file(s)] by [Author Tag]: [brief summary of changes]"`
|
||||
* `git push origin <current_branch>`.
|
||||
5. **Visibility for Push Failures:** Push failures must be reported directly to the console/session output, never swallowed silently.
|
||||
|
||||
---
|
||||
|
||||
### **2. Reliable Wrap-up Commit + Push (Automation Design)**
|
||||
|
||||
To prevent state loss due to crashes or skipped wrap-ups.
|
||||
|
||||
**A. Recommended Mechanism: Harness Stop Hook**
|
||||
|
||||
The primary mechanism will be a harness-level stop hook, which executes reliable git operations regardless of user-triggered wrap-up or session termination.
|
||||
|
||||
* **Placement:**
|
||||
* **Pi:** `~/.pi/agent/settings.json` (or equivalent harness configuration).
|
||||
* **Claude Code:** `~/.claude/agent/settings.json` (or equivalent harness configuration).
|
||||
* **Action:** Execute a script (e.g., `update_repo_on_stop.sh`) when the agent session stops. This script will generalize the `current-state.md` logic to any modified file within the working repository.
|
||||
* **`update_repo_on_stop.sh` Script Logic (Conceptual):**
|
||||
```bash
|
||||
#!/bin/bash
|
||||
PRIMARY_REPO_ROOT="/Users/sttil-solutions/projects/signal" # Target the main project repo
|
||||
|
||||
# --- Generic Git Auto-Commit & Push Logic ---
|
||||
# This script is a generalized abstraction. Actual implementation needs to identify
|
||||
# which Git repositories are active (e.g., "$PRIMARY_REPO_ROOT", "~/.claude/skills/")
|
||||
# and perform operations for each.
|
||||
|
||||
handle_repo() {
|
||||
local repo_path=$1
|
||||
local branch_name="main" # Or dynamically determine current branch
|
||||
cd "$repo_path" || { echo "ERROR: Could not change directory to $repo_path" >&2; return 1; }
|
||||
|
||||
if git diff --quiet || git diff --cached --quiet; then
|
||||
echo "Repository $repo_path is clean, no auto-commit needed."
|
||||
return 0
|
||||
fi
|
||||
|
||||
echo "Pending changes detected in $repo_path. Attempting auto-commit/push."
|
||||
|
||||
# Stage all changes that are not untracked
|
||||
git add .
|
||||
|
||||
# Attempt to commit
|
||||
local commit_message="Auto-commit pending changes via stop hook. [$(hostname)]"
|
||||
if ! git commit -m "$commit_message"; then
|
||||
echo "WARNING: Failed to auto-commit changes in $repo_path. May be due to other unstaged/untracked files or a dirty index for some files." >&2
|
||||
echo "Please inspect manually: cd $repo_path && git status" >&2
|
||||
# Stash if necessary to clean working directory, but don't lose changes
|
||||
# if ! git diff --quiet; then
|
||||
# echo "Attempting to stash remaining uncommitted changes." >&2
|
||||
# git stash push --message "Auto-stashed by stop hook: $repo_path" >&2
|
||||
# fi
|
||||
return 1 # Indicate failure
|
||||
fi
|
||||
|
||||
# Pull and rebase before push
|
||||
if ! git pull --rebase origin "$branch_name"; then
|
||||
echo "WARNING: Auto-push failed for $repo_path due to rebase conflict. Please resolve manually: cd $repo_path && git status" >&2
|
||||
return 1
|
||||
fi
|
||||
|
||||
# Push
|
||||
if ! git push origin "$branch_name"; then
|
||||
echo "WARNING: Auto-push failed for $repo_path. Please push manually: cd $repo_path && git push" >&2
|
||||
return 1
|
||||
fi
|
||||
echo "Successfully auto-committed and pushed pending changes in $repo_path."
|
||||
return 0
|
||||
}
|
||||
|
||||
# Handle primary project repo
|
||||
handle_repo "$PRIMARY_REPO_ROOT"
|
||||
|
||||
# Handle skills repo if it's a separate Git repo (e.g., "~/.claude/skills/")
|
||||
# SKILLS_REPO_ROOT="~/.claude/skills" # This path needs to be absolute and correctly resolved by the shell
|
||||
# handle_repo "$SKILLS_REPO_ROOT"
|
||||
```
|
||||
* **Push Failure Visibility:** The script above ensures push failures are explicitly echoed to `stderr`, making them visible in the agent's log/terminal history.
|
||||
* **Session-Brain Step 5:** The `navaigate-session-brain` Step 5 remains the rich, user-triggered wrap-up path, offering more control and context.
|
||||
|
||||
---
|
||||
|
||||
### **3. Skills + MCP Parity (Claude ↔ Pi)**
|
||||
|
||||
**A. Skills Parity**
|
||||
|
||||
* **Shared Directory:** `~/.claude/skills/` remains the single, shared skill library.
|
||||
* **Skills Version Control:** `~/.claude/skills/` will itself be a Git repository (e.g., cloned from `forgejo.sttilsolutions.com/sttil-platform/sttil-skills.git`). This ensures all skills are version-controlled, traceable, and synchronized across agents via `git pull` at startup.
|
||||
* **`~/.pi/agent/AGENTS.md` Update:**
|
||||
* **Existing Text (to be replaced):** The hand-maintained table mapping skill names to files.
|
||||
* **New Text:** Replace the table with a declarative statement and a guide for skill discovery.
|
||||
```markdown
|
||||
# Available Skills
|
||||
|
||||
Pi and Claude Code share a unified, version-controlled skill library located at `~/.claude/skills/` (a Git repository automatically updated at session startup).
|
||||
To use a skill, invoke it by its name after loading its respective `SKILL.md` file.
|
||||
|
||||
**Skill Discovery:** To see available skills, consult the contents of `~/.claude/skills/` which is the Git repository cloned from `forgejo.sttilsolutions.com/sttil-platform/sttil-skills.git`.
|
||||
```
|
||||
|
||||
**B. MCP Parity (Common Server Configuration)**
|
||||
|
||||
* **Shared MCP Configuration File:** Introduce a git-versioned plain-text file (e.g., `signal/context/shared_mcp_config.json`) within the `signal` repo. This file will define common MCP server connections (e.g., `trilane`).
|
||||
* **Harness Load Hook:** Implement a lightweight hook in both Pi and Claude Code's harness configurations that executes on startup/connect:
|
||||
* Reads `signal/context/shared_mcp_config.json`.
|
||||
* Dynamically registers or updates their respective `mcp.json` or in-memory MCP server list.
|
||||
* **Non-Shared MCPs:** `graphify` and `use-railway` will continue to be configured directly within Claude Code's specific `mcp.json` as needed, outside the shared file.
|
||||
|
||||
---
|
||||
|
||||
### **4. Drift-to-Skill Governance (Decision Table)**
|
||||
|
||||
This table categorizes recurring manual activities and recommends their automation strategy.
|
||||
|
||||
| Manual Protocol | Current Behavior | Recommended Automation | Type | Build By (Agent) | Notes |
|
||||
| :------------------------------------ | :---------------------------------------------------- | :----------------------- | :------------ | :--------------- | :------------------------------------------------------------------------------------------------------- |
|
||||
| Session Start Git Pulls | Manual `git pull`, `read` command (per repo) | **Automated Read Protocol** | Hook | Pi / Claude | Applies to `signal` repo and `~/.claude/skills` repo (if separate). |
|
||||
| Session Wrap-up Auto-commit/push | Manual `edit`, `commit`, `push` (`navaigate-session-brain` Step 5) | **Automated Write Protocol** | Hook | Pi / Claude | Generalized to auto-commit/push all changes in managed Git repos. |
|
||||
| Git Commit + Push (general) | Manual `git add`, `commit`, `push` | **Skill** | Skill | Claude | A general `/git-push` skill for other work. |
|
||||
| Content Calendar Update (NocoDB) | Manual curl/GUI update | **Skill** | Skill | Pi / Claude | "Update NocoDB content calendar" skill (might use `mcp` if NocoDB is an MCP server). |
|
||||
| KG Queries (TriLane) | Manual TriLane `mcp` calls (now HTTP `curl`) | **Skill** | Skill | Pi / Claude | "Query TriLane" skill (e.g., `/trilane-query`), using the documented HTTP API. |
|
||||
| `current-state.md` Staleness Check | Manual check of `Updated:` timestamp | **Automated Read Protocol** | Hook | Pi / Claude | Defined in Section 1.C. |
|
||||
| MCP Server Sync | Manual `mcp connect` for each agent | **Automated MCP Parity** | Hook | Pi / Claude | Reads `shared_mcp_config.json` at startup. |
|
||||
| New Policy/Doc (e.g., regulatory summary) | Manual creation/updates | **Skill** | Skill | Pi / Claude | Skill to draft/update documents (e.g., `/write-policy`, `/summarize-regulation`), committing changes. |
|
||||
| Blog Post Creation/Update | Manual | **Skill Pipeline** | Workflow | Pi / Claude | Automated blog content pipeline, committing posts to blog repo (see Automated Blog Plan). |
|
||||
|
||||
---
|
||||
|
||||
### **5. Cleanup / Smoother Workflow**
|
||||
|
||||
This outlines the broader housekeeping changes for coherent start/wrap protocols.
|
||||
|
||||
* **Retire `project_next_steps.md`:** This file will no longer be maintained as its purpose is entirely superseded by the `NEXT` section of `current-state.md`. Claude's internal memory should be updated to no longer reference/expect this file.
|
||||
* **Demote Embedded "Current State" in `CLAUDE.md`:**
|
||||
* **Existing Text (in `signal/CLAUDE.md`):**
|
||||
```markdown
|
||||
## Current State (embedded — always in context)
|
||||
**ACTIVE:** Claude Code built Phase 2 (verified). Pi applied trust fixes, wrote Phase 4 spec, completed Shield competitor recon.
|
||||
**NEXT:** Pi designs Shield architecture (standalone compliance product). Claude Code on website review + whitepaper + Phase 2 verification.
|
||||
... (rolling fields) ...
|
||||
**At session START:** use this section for state. Then read `context/current-state.md` for the full shared state (decisions, stack details).
|
||||
**At WRAP-UP:** update this section AND `context/current-state.md` (keep both in sync).
|
||||
```
|
||||
* **New Text (`signal/CLAUDE.md` startup edit):**
|
||||
```markdown
|
||||
## Current State (deprecated — see `context/current-state.md`)
|
||||
**Purpose:** This block is deprecated due to state drift. For the active, canonical project state, always refer to `signal/context/current-state.md`.
|
||||
```
|
||||
* **Implication:** This ensures the harness auto-injects a trivial string for `CLAUDE.md`'s "Current State" reducing token usage and eliminating confusion.
|
||||
* **Coherent Start/Wrap Protocol:** The combined read/write protocols (Section 1.C, 1.D, 2.A) form a unified process for both Pi and Claude.
|
||||
* **`current-state.md` per Repo:** This design explicitly maintains `context/current-state.md` within the `signal` repo, reinforcing the principle of one state file per logical project repository where agents are active.
|
||||
|
||||
---
|
||||
|
||||
### **Universal Git Version Control (Golden Nugget Integration)**
|
||||
|
||||
This overarching principle applies across all workstreams:
|
||||
|
||||
**Principle:** **All human-readable, agent-readable, and machine-actionable artifacts that constitute stable project knowledge, configuration, active state, or output should be managed under Git version control.**
|
||||
|
||||
* **Skills (`~/.claude/skills/`):** Should be a dedicated Git repository. Changes to skills are versioned, traceable, and synchronized across agents via `git pull --rebase` at agent startup.
|
||||
* **Internal Policies & Operational Documentation (`docs/compliance/`, etc.):** Critical for auditability and consistency. All such documents (e.g., privacy policies, data-handling procedures, API contracts) must be versioned in Git. Agents (or humans) draft changes, commit, and push.
|
||||
* **External Regulatory Summaries & Payer Rule Interpretations (`docs/regulatory_summaries/`, `payer_rules.json`):** Git provides a precise, auditable history of when these interpretations changed, crucial for compliance logic (`Signal` and `Shield`). When a research agent flags an external change, its *processed interpretation* and any derived rule updates are committed to Git with clear commit messages and timestamps.
|
||||
* **Automated Blog Content:** Each blog post's content (e.g., Markdown files) and associated metadata (e.g., Schema.org JSON-LD) are versioned in Git. Git pushes can automatically trigger publication via CI/CD.
|
||||
* **TriLane as Intelligence Layer:** Git-versioned artifacts serve as concrete, traceable inputs for TriLane. A commit hash can be a direct citation for a `research_insight` in TriLane. TriLane *correlates* these versioned inputs to produce higher-level market projections and strategic guidance, which can then be used by agents to draft blog posts or update other Git-managed documents. This creates a powerful feedback loop where Git provides the auditable granular changes, and TriLane provides the strategic macro-level insights.
|
||||
|
||||
This enhancement ensures a robust, trustworthy, and self-maintaining flow of information and work across the entire STTIL Solutions agent ecosystem.
|
||||
|
||||
---
|
||||
|
||||
### **Deliverable Summary**
|
||||
|
||||
This revised design document provides:
|
||||
|
||||
1. **`current-state.md` Schema (`v:1`) and Template:** (Section 1.A)
|
||||
2. **Read/Write Protocol Steps:** (Section 1.C, 1.D) ready for inclusion in shared skill startup/wrap-up logic.
|
||||
3. **De-duplication Map:** (Section 1.B)
|
||||
4. **Recommended Wrap-up Automation (Harness Stop Hook):** (Section 2.A) including conceptualized `update_repo_on_stop.sh` script logic and placement.
|
||||
5. **Skills/MCP Parity Fixes:** (Section 3) with exact proposed edits for `~/.pi/agent/AGENTS.md` and mechanism for `shared_mcp_config.json`.
|
||||
6. **Drift-to-Skill Decision Table:** (Section 4)
|
||||
7. **Exact Startup Edits for `CLAUDE.md`:** (Section 5)
|
||||
8. **Golden Nugget Integration:** Explicitly details the **Universal Git Version Control** strategy across all relevant artifact types, solidifying the foundation for STTIL Solutions' agent-driven workflow.
|
||||
|
||||
This comprehensive and now finalized design is ready for Claude Code's implementation phase.
|
||||
|
||||
---
|
||||
|
||||
**Next: Session Brain Update (Wrap-up)**
|
||||
|
||||
I will now update `current-state.md` to reflect the completion and finalization of this workflow consolidation design, providing clear next steps for Claude Code to implement it. This will also mark the end of this session.
|
||||
|
||||
---
|
||||
|
||||
I've made the updates to `current-state.md` regarding the workflow consolidation design, but part of the final "Updated" timestamp edit failed due to a mismatch. I need to re-read the `current-state.md` to get the exact `oldText` for the `Updated:` line and then apply the final change.
|
||||
|
||||
---
|
||||
|
||||
The `current-state.md` is now fully updated, reflecting the completion and finalization of the workflow consolidation design, including the universal Git versioning strategy. The next steps for Claude Code (implementing the workflow consolidation and building the readiness model) are clearly documented.
|
||||
|
||||
This formally concludes my work on this goal.
|
||||
|
||||
|
||||
Loading…
Reference in a new issue