Kisa 00cff7a5f8 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>

2026-06-23 23:30:56 -04:00

38 KiB

Raw Blame History

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:

Integrate the "golden nuggets" regarding expanded Git version control into the workflow consolidation design document.
Confirm the updated design is final.
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)

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)

git pull --rebase origin <current_branch>: Fetch latest changes and rebase local branch to ensure working on the freshest state for the primary repository.
git pull --rebase origin <skills_repo_branch>: If skills are in a separate Git repo, update them.
Read signal/context/current-state.md: Load file contents into agent's short-term context.
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)

Single Mutable Head: Agents may only directly modify the ACTIVE and NEXT sections.
Append-Only Decisions Log: All new decisions must be appended to the Decisions section, prefixed with [YYYY-MM-DD]: [Decision Summary. [Author Tag]].
Update Updated: Timestamp: The Updated: line at the bottom must be updated to the current date and a brief status summary.
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>.
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):

#!/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.

# 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):

## 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):

## 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:

current-state.md Schema (v:1) and Template: (Section 1.A)
Read/Write Protocol Steps: (Section 1.C, 1.D) ready for inclusion in shared skill startup/wrap-up logic.
De-duplication Map: (Section 1.B)
Recommended Wrap-up Automation (Harness Stop Hook): (Section 2.A) including conceptualized update_repo_on_stop.sh script logic and placement.
Skills/MCP Parity Fixes: (Section 3) with exact proposed edits for ~/.pi/agent/AGENTS.md and mechanism for shared_mcp_config.json.
Drift-to-Skill Decision Table: (Section 4)
Exact Startup Edits for CLAUDE.md: (Section 5)
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:

Integrate the "golden nuggets" regarding expanded Git version control into the workflow consolidation design document.
Confirm the updated design is final.
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

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)

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)

git pull --rebase origin <current_branch>: Fetch latest changes and rebase local branch to ensure working on the freshest state for the primary repository.
git pull --rebase origin <skills_repo_branch>: If skills are in a separate Git repo, update them.
Read signal/context/current-state.md: Load file contents into agent's short-term context.
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)

Single Mutable Head: Agents may only directly modify the ACTIVE and NEXT sections.
Append-Only Decisions Log: All new decisions must be appended to the Decisions section, prefixed with [YYYY-MM-DD]: [Decision Summary. [Author Tag]].
Update Updated: Timestamp: The Updated: line at the bottom must be updated to the current date and a brief status summary.
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>.
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):

#!/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.

# 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):

## 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):

## 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:

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:

current-state.md Schema (v:1) and Template: (Section 1.A)
Read/Write Protocol Steps: (Section 1.C, 1.D) ready for inclusion in shared skill startup/wrap-up logic.
De-duplication Map: (Section 1.B)
Recommended Wrap-up Automation (Harness Stop Hook): (Section 2.A) including conceptualized update_repo_on_stop.sh script logic and placement.
Skills/MCP Parity Fixes: (Section 3) with exact proposed edits for ~/.pi/agent/AGENTS.md and mechanism for shared_mcp_config.json.
Drift-to-Skill Decision Table: (Section 4)
Exact Startup Edits for CLAUDE.md: (Section 5)
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'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.

38 KiB Raw Blame History Unescape Escape

Workflow Consolidation — Pi Design (RECOVERED from Pi session log 2026-06-24)

Revised Design Document: Workflow Consolidation for STTIL Agents

1. The State Contract: current-state.md Schema & Protocol

2. Reliable Wrap-up Commit + Push (Automation Design)

3. Skills + MCP Parity (Claude ↔ Pi)

4. Drift-to-Skill Governance (Decision Table)

5. Cleanup / Smoother Workflow

Universal Git Version Control (Golden Nugget Integration)

Deliverable Summary

Revised Design Document: Workflow Consolidation for STTIL Agents

1. The State Contract: current-state.md Schema & Protocol

2. Reliable Wrap-up Commit + Push (Automation Design)

3. Skills + MCP Parity (Claude ↔ Pi)

4. Drift-to-Skill Governance (Decision Table)

5. Cleanup / Smoother Workflow

Universal Git Version Control (Golden Nugget Integration)

Deliverable Summary

38 KiB

Raw Blame History

1. The State Contract: `current-state.md` Schema & Protocol

1. The State Contract: `current-state.md` Schema & Protocol