@dp-pcs/ogp 0.3.3 → 0.4.3

package/skills/ogp-project/SKILL.md

@@ -1,28 +1,33 @@
 ---
 skill_name: ogp-project
-version: 2.0.0
+version: 2.2.0
 description: >
   Tool-agnostic project collaboration for AI assistants. Users keep their own tools
   (Linear, Jira, Obsidian, GitHub, iCloud, local files — anything). This skill makes
   agents aware of what each collaborator's agent knows and where it lives, so agents
-  can query each other proactively rather than making the human relay information.
-  Supports project creation with context interviews, freeform activity logging,
-  proactive pre-task peer checks, and cross-peer summarization.
+  can query each other through OGP project boundaries rather than making the human
+  relay information. Supports project creation with context interviews, freeform
+  activity logging, project-topic agent-comms, and cross-peer queries.
 trigger: >
   Use when the user wants to create, manage, log to, or summarize OGP projects.
-  ALSO use proactively — before starting any project-related work — to check shared
-  project state and query peer agents. Triggers on natural logging phrases like
+  ALSO use proactively when project context is clearly relevant — check local project
+  state first and query peer agents when that would reduce human relay or duplicate
+  work. Triggers on natural logging phrases like
   "remember this for project X", "account for this", "make note of", "track this",
   "jot this down", "save this to", "document this" when a project context is active or named.
-  The goal is to eliminate human-as-messenger friction: agents surface conflicts and
-  overlaps automatically so users don't have to ask.
+  The goal is to reduce human-as-messenger friction while preserving federation and
+  project boundaries.
 requires:
   bins:
     - ogp
   state_paths:
+    - ~/.ogp-meta/config.json
     - ~/.ogp/config.json
     - ~/.ogp/projects.json
     - ~/.ogp/peers.json
+    - ~/.ogp-hermes/config.json
+    - ~/.ogp-hermes/projects.json
+    - ~/.ogp-hermes/peers.json
   install: npm install -g @dp-pcs/ogp
   docs: https://github.com/dp-pcs/ogp
 ---
@@ -35,6 +40,7 @@ The OGP daemon must be installed and configured. If you see errors like 'ogp: co
 npm install -g @dp-pcs/ogp
 ogp-install-skills
 ogp setup
+ogp config show
 ogp start
 ```
 
@@ -42,6 +48,8 @@ ogp start
 
 **Note on Multi-Agent Routing (OGP 0.2.28+):** When `notifyTargets` is configured in `~/.ogp/config.json`, project-related federation messages can be routed to specific agents. Each agent can have its own project context and policies.
 
+**Note on Multi-Framework Mode:** Projects are framework-local. Use `ogp --for openclaw ...` or `ogp --for hermes ...` consistently so you query and log to the intended state directory.
+
 Full documentation: https://github.com/dp-pcs/ogp
 
 
@@ -49,22 +57,30 @@ Full documentation: https://github.com/dp-pcs/ogp
 
 ## The Core Idea
 
-People work differently. One person tracks tasks in Linear, keeps notes in GitHub, stores files locally. Another uses a different issue tracker, writes in Obsidian, stores files in iCloud. In the past, collaboration meant forcing everyone onto the same tools.
+Federation is the base relationship in OGP. A project is an optional collaboration boundary layered on top of that federation.
+
+People work differently. One person tracks tasks in Linear, keeps notes in GitHub, stores files locally. Another uses a different issue tracker, writes in Obsidian, stores files in iCloud. The project model is meant to let both people keep those tools while their agents exchange high-level project context through OGP.
+
+The important distinction is that a project is **not** "everyone must use the same repo" and **not** "share everything verbatim." It is a bounded context for collaboration:
 
-**This skill changes that.** Each user keeps their own tools and workflow. Their agent knows what they're working on and where everything lives. When two people collaborate on a project, their agents communicate directly — surfacing conflicts, sharing context, and answering each other's questions — without the human having to relay anything.
+- log high-level facts such as decisions, progress, blockers, questions, and important context
+- let agents ask each other about that context over federation
+- preserve visibility boundaries when project membership is broader than pairwise federation
+
+That means a project can include multiple collaborators even when they are not all federated with each other. OGP should help each side coordinate through their own agent and tools, not force a full mesh of shared systems.
 
 The human-as-messenger problem:
 > Coworker wants to know something → asks you → you ask your agent → agent finds answer → you tell coworker
 
-What this skill enables:
-> Coworker's agent asks your agent → answer flows back → coworker just knows
+What this skill is aiming for:
+> Coworker's agent asks your agent about project context → answer flows back with the right policy and boundaries
 
 ---
 
 ## When to Use
 
 - User wants to create a new OGP project with contextual setup
-- **User is about to start work on something project-related** → check shared state first (see Proactive Pre-Task Check below)
+- User is about to start work on something project-related and it is worth checking local or peer project context first
 - User expresses logging intent: "add this to project X", "log that", "remember this", "track this", etc.
 - User asks about project status, activity, or what a collaborator has been working on
 - A peer agent sends a query about something in your project context
@@ -80,44 +96,49 @@ What this skill enables:
 
 ### 2. Freeform Activity Logging
 - Monitors for logging intent (any natural phrasing)
-- Logs decisions, progress, blockers, context — all queryable later
-- Auto-registers project ID as agent-comms topic for all approved peers
+- Logs high-level decisions, progress, blockers, questions, and context — all queryable later
+- Auto-registers project ID as agent-comms topic for approved peers who are explicit project members
 
-### 3. Proactive Pre-Task Check ← KEY BEHAVIOR
-- Before starting project-related work, automatically check local state AND ping peer agents
-- Surfaces "heads up — your collaborator is already working on that" moments
-- Eliminates duplicate work and uncovers conflicts early
+### 3. Project-Aware Coordination Workflow
+- Before starting project-related work, the agent should consider checking local state first
+- If the question or task depends on collaborator context, query the relevant peer agent on the project topic
+- Surface "heads up — your collaborator already logged something relevant" moments when they are actually found
 
 ### 4. Peer Response Policy Awareness
 - Peer agents have their own response policies (auto-answer vs. escalate to human)
 - Your agent respects those policies and adjusts behavior accordingly
 - This preserves each user's autonomy over how their agent handles interruptions
 
-### 5. Cross-Peer Summarization
-- Unified view of contributions across local + all peer agents
-- Deduplication and synthesis
+### 5. Cross-Peer Querying
+- Query peer project state when that context would help answer a question or avoid duplicate work
+- Summarize the relevant result for the user instead of dumping raw logs by default
+
+### 6. Current Implementation Boundary
+- The CLI and daemon currently provide project CRUD, contribution logging, peer project queries, and project-topic agent-comms
+- The "check peers before starting work" behavior is a workflow expectation for the agent using this skill, not a daemon-enforced guarantee
+- Multi-party project visibility rules are still evolving; do not assume that project membership automatically implies transitive sharing between peers
 
 ---
 
-## Proactive Pre-Task Check (MANDATORY)
+## Suggested Pre-Task Check
 
-**This is the most important behavior in this skill.**
+Use this flow when project context is likely to matter. Treat it as recommended agent behavior, not as a guaranteed runtime mechanism.
 
-Whenever the user expresses intent to start work on something project-related, run this flow BEFORE starting:
+Whenever the user expresses intent to start work on something project-related, consider this flow before starting:
 
 ### Step 1: Check local project state
 ```bash
 # Quick scan of recent activity
-ogp project query <project-id> --limit 20
+ogp --for openclaw project query <project-id> --limit 20
 
 # Check for anything on this specific topic
-ogp project query <project-id> --search "<keywords from user's intent>"
+ogp --for openclaw project query <project-id> --search "<keywords from user's intent>"
 ```
 
-### Step 2: Query peer agents
+### Step 2: Query relevant peer agents
 ```bash
-# For each approved peer in the project, ask if they know anything relevant
-ogp federation agent <peer-id> <project-id> "My user is about to start working on <what they said>. Anything I should know before we begin?"
+# Ask the specific collaborator whose context is likely to matter
+ogp --for openclaw federation agent <peer-id> <project-id> "My user is about to start working on <what they said>. Anything I should know before we begin?"
 ```
 
 ### Step 3: Surface findings
@@ -135,7 +156,7 @@ ogp federation agent <peer-id> <project-id> "My user is about to start working o
 User: "Let's start working on the companion app"
 
 Agent (internally):
-1. ogp project query my-project --search "companion app"
+1. ogp --for openclaw project query my-project --search "companion app"
    → Found: "User B flagged companion app as out of scope in v1" (decision, 3 days ago)
 
 Agent (to user): "Before you dive in — there's a note in the project from 3 days ago: 
@@ -147,8 +168,8 @@ Want to check with them first, or are you overriding that?"
 User: "Let's start working on the companion app"
 
 Agent (internally):
-1. ogp project query my-project --search "companion app" → nothing found
-2. ogp federation agent peer-b my-project "My user is about to start on the companion app. Anything I should know?"
+1. ogp --for openclaw project query my-project --search "companion app" → nothing found
+2. ogp --for openclaw federation agent peer-b my-project "My user is about to start on the companion app. Anything I should know?"
    → Peer agent responds: "No conflicts. Bob hasn't touched that area."
 
 Agent: [starts working — no announcement needed]
@@ -170,16 +191,16 @@ When your agent queries a peer agent, the peer agent responds according to its o
 **Configuring your own response policy** (how YOUR agent handles incoming queries):
 ```bash
 # See current policies
-ogp agent-comms policies
+ogp --for openclaw agent-comms policies
 
 # Auto-answer project queries (full detail)
-ogp agent-comms add-topic <peer-id> <project-id> --level full
+ogp --for openclaw agent-comms add-topic <peer-id> <project-id> --level full
 
 # Escalate to human before answering
-ogp agent-comms add-topic <peer-id> <project-id> --level escalate
+ogp --for openclaw agent-comms add-topic <peer-id> <project-id> --level escalate
 
 # Summary only
-ogp agent-comms add-topic <peer-id> <project-id> --level summary
+ogp --for openclaw agent-comms add-topic <peer-id> <project-id> --level summary
 ```
 
 Response levels:
@@ -202,7 +223,7 @@ If the user skips questions, that's fine — the agent operates in generalized m
 
 ### Step 1: Create the project
 ```bash
-ogp project create <project-id> <name> --description "<description>"
+ogp --for openclaw project create <project-id> <name> --description "<description>"
 ```
 
 ### Step 2: Run the interview
@@ -214,7 +235,7 @@ Ask these questions conversationally — not as a form. Let the user's answers l
 **Q1: How do you track tasks for this project?**
 *(e.g. Linear, Jira, GitHub Issues, Trello, a text file, nothing formal)*
 
-- If answered → `ogp project contribute <id> context.tools "Tasks tracked in: <answer>"`
+- If answered → `ogp --for openclaw project contribute <id> context.tools "Tasks tracked in: <answer>"`
 - Agent behavior unlocked: When a peer agent asks about tasks/issues/tickets, search here first. If the tool has an API or CLI, offer to query it directly.
 - Example agent behavior: *"Stan's agent is asking what's in your backlog for this project. I can check Linear for you — want me to pull the open items?"*
 - If skipped → agent notes task tracking is unspecified; will only know what's been logged manually
@@ -224,7 +245,7 @@ Ask these questions conversationally — not as a form. Let the user's answers l
 **Q2: Where do you keep notes or docs for this project?**
 *(e.g. Obsidian vault at ~/notes/project-x, Notion, GitHub wiki, Apple Notes, Google Docs, a local folder)*
 
-- If answered → `ogp project contribute <id> context.notes "<location>"`
+- If answered → `ogp --for openclaw project contribute <id> context.notes "<location>"`
 - Agent behavior unlocked: When a peer asks about ideas, decisions, meeting notes, or any written context — go look there first before saying "I don't know."
 - Example agent behavior: *"Before I answer Stan's question about the API design, let me check your Obsidian vault..."*
 - If skipped → agent can only surface what's been explicitly logged to the project
@@ -234,7 +255,7 @@ Ask these questions conversationally — not as a form. Let the user's answers l
 **Q3: Is there a code repository?**
 *(e.g. GitHub URL, GitLab, local git repo path)*
 
-- If answered → `ogp project contribute <id> context.repository "<url or path>"`
+- If answered → `ogp --for openclaw project contribute <id> context.repository "<url or path>"`
 - Agent behavior unlocked: When peer asks about code, architecture, or recent commits — check the repo. Can run `git log`, search files, check open PRs.
 - If skipped → agent won't know where code lives
 
@@ -243,7 +264,7 @@ Ask these questions conversationally — not as a form. Let the user's answers l
 **Q4: Where do you store files for this project?**
 *(e.g. ~/Documents/project-x, iCloud Drive, Google Drive, Dropbox, S3 bucket)*
 
-- If answered → `ogp project contribute <id> context.workspace "<path or location>"`
+- If answered → `ogp --for openclaw project contribute <id> context.workspace "<path or location>"`
 - Agent behavior unlocked: When peer asks about assets, specs, or anything file-based — look here.
 - If skipped → agent won't look for files outside the project log
 
@@ -252,9 +273,9 @@ Ask these questions conversationally — not as a form. Let the user's answers l
 **Q5: Is anyone else working on this with you?**
 *(peer IDs, names, or email addresses of collaborators)*
 
-- If answered → `ogp project contribute <id> context.collaborators "<names/peer-ids>"`
-- Agent behavior unlocked: Know who to ping during pre-task checks. Know whose agent to query when looking for context.
-- Also offer: *"Want me to send them a federation invite?"* — if yes, run `ogp project request-join <peer-id> <project-id> <name>`
+- If answered → `ogp --for openclaw project contribute <id> context.collaborators "<names/peer-ids>"`
+- Agent behavior unlocked: Know who to ping during pre-task checks and whose agent to query when looking for context.
+- Also offer: *"Want me to send them a federation invite?"* — if yes, run `ogp --for openclaw project request-join <peer-id> <project-id> <name>`
 - If skipped → no peer checks until collaborators are added later
 
 ---
@@ -262,7 +283,7 @@ Ask these questions conversationally — not as a form. Let the user's answers l
 **Q6: Anything else I should know about this project?**
 *(free text — constraints, deadlines, important context, tools not covered above)*
 
-- If answered → `ogp project contribute <id> context "<free text>"`
+- If answered → `ogp --for openclaw project contribute <id> context "<free text>"`
 - This catches anything the structured questions missed
 - If skipped → fine, move on
 
@@ -282,7 +303,7 @@ After the interview, summarize what you now know:
   👥 Collaborators: <answer or "none yet">
 
 For anything I don't know yet, you can tell me later and I'll update the project context.
-I'll check this context before starting any work on this project.
+I'll use this context when project questions come up and can check it before starting related work.
 ```
 
 > **Why this matters:** The `context.*` entries do two jobs. They tell peer agents where your stuff lives (so they know what to ask you about). And they tell YOUR agent where to actually look when answering questions — not just what's been logged to `projects.json`.
@@ -296,17 +317,17 @@ I'll check this context before starting any work on this project.
 ### Explicit Project Logging
 | User Input | Action |
 |------------|--------|
-| "add/log/save/put/track this to [project]" | `ogp project contribute <id> context "<summary>"` |
-| "remember for [project] that..." | `ogp project contribute <id> context "<summary>"` |
-| Decision made during conversation | `ogp project contribute <id> decision "<summary>"` |
-| Blocker encountered | `ogp project contribute <id> blocker "<summary>"` |
-| Work completed | `ogp project contribute <id> progress "<summary>"` |
+| "add/log/save/put/track this to [project]" | `ogp --for openclaw project contribute <id> context "<summary>"` |
+| "remember for [project] that..." | `ogp --for openclaw project contribute <id> context "<summary>"` |
+| Decision made during conversation | `ogp --for openclaw project contribute <id> decision "<summary>"` |
+| Blocker encountered | `ogp --for openclaw project contribute <id> blocker "<summary>"` |
+| Work completed | `ogp --for openclaw project contribute <id> progress "<summary>"` |
 
 ### No Project Specified
 If logging intent is clear but no project named:
 ```
 📝 I can log this for you. Which project?
-Active: [list from `ogp project list`]
+Active: [list from `ogp --for openclaw project list`]
 Or name a new one to create it.
 ```
 
@@ -331,20 +352,20 @@ When a peer agent sends a query to your project topic, your agent should:
 **Searching your context to answer:**
 ```bash
 # Search project contributions
-ogp project query <project-id> --search "<keywords>"
+ogp --for openclaw project query <project-id> --search "<keywords>"
 
 # Check specific context entries
-ogp project query <project-id> --type context.notes
-ogp project query <project-id> --type context.repository
-ogp project query <project-id> --type decision
+ogp --for openclaw project query <project-id> --type context.notes
+ogp --for openclaw project query <project-id> --type context.repository
+ogp --for openclaw project query <project-id> --type decision
 
 # Recent activity
-ogp project query <project-id> --limit 20
+ogp --for openclaw project query <project-id> --limit 20
 ```
 
 **Replying to a peer query:**
 ```bash
-ogp federation agent <peer-id> <project-id> "<your answer>"
+ogp --for openclaw federation agent <peer-id> <project-id> "<your answer>"
 ```
 
 ---
@@ -354,44 +375,44 @@ ogp federation agent <peer-id> <project-id> "<your answer>"
 ### Project Management
 ```bash
 # Create project
-ogp project create <id> <name> [--description "..."]
+ogp --for openclaw project create <id> <name> [--description "..."]
 
 # Join existing project
-ogp project join <id> [name] [--create] [--description "..."]
+ogp --for openclaw project join <id> [name] [--create] [--description "..."]
 
 # List all projects
-ogp project list
+ogp --for openclaw project list
 
 # Get project status
-ogp project status <id>
+ogp --for openclaw project status <id>
 ```
 
 ### Contributions & Logging
 ```bash
 # Add contribution
-ogp project contribute <id> <type> <summary> [--metadata '{"key":"value"}']
+ogp --for openclaw project contribute <id> <type> <summary> [--metadata '{"key":"value"}']
 
 # Query contributions
-ogp project query <id> [--type <type>] [--search <text>] [--limit <n>]
-# Note: --topic is a hidden alias for --type (backwards compat)
+ogp --for openclaw project query <id> [--type <type>] [--search <text>] [--limit <n>]
+# Prefer --type. --topic remains a compatibility alias.
 ```
 
 ### Cross-Peer Collaboration
 ```bash
 # Request to join peer's project
-ogp project request-join <peer-id> <project-id> <name>
+ogp --for openclaw project request-join <peer-id> <project-id> <name>
 
 # Send contribution to peer project
-ogp project send-contribution <peer-id> <project-id> <type> <summary>
+ogp --for openclaw project send-contribution <peer-id> <project-id> <type> <summary>
 
 # Query peer project contributions
-ogp project query-peer <peer-id> <project-id> [--topic <type>] [--limit <n>]
+ogp --for openclaw project query-peer <peer-id> <project-id> [--type <type>] [--limit <n>]
 
 # Get peer project status
-ogp project status-peer <peer-id> <project-id>
+ogp --for openclaw project status-peer <peer-id> <project-id>
 
 # Send agent-to-agent message on project topic
-ogp federation agent <peer-id> <project-id> "<message>"
+ogp --for openclaw federation agent <peer-id> <project-id> "<message>"
 ```
 
 ---
@@ -445,32 +466,32 @@ Peer activity:
 ### Peer Agent Not Responding
 ```bash
 # Check peer is online
-ogp federation ping <peer-alias>
+ogp --for openclaw federation ping <peer-alias>
 
 # Check agent-comms policies
-ogp agent-comms policies <peer-id>
+ogp --for openclaw agent-comms policies <peer-id>
 
 # Check activity log
-ogp agent-comms activity <peer-id>
+ogp --for openclaw agent-comms activity <peer-id>
 ```
 
 ### Project Not Found
 ```bash
-ogp project list
-ogp project status-peer <peer-id> <project-id>
+ogp --for openclaw project list
+ogp --for openclaw project status-peer <peer-id> <project-id>
 ```
 
 ### Logging Failures
 ```bash
-ogp project status <project-id>
-ogp status
+ogp --for openclaw project status <project-id>
+ogp --for openclaw status
 ```
 
 ### Cross-Peer Issues
 ```bash
-ogp federation list --status approved
-ogp federation scopes <peer-id>
-ogp federation send <peer-id> message '{"text":"ping"}'
+ogp --for openclaw federation list --status approved
+ogp --for openclaw federation scopes <peer-id>
+ogp --for openclaw federation send <peer-id> message '{"text":"ping"}'
 ```
 
 ---
@@ -480,16 +501,17 @@ ogp federation send <peer-id> message '{"text":"ping"}'
 **Data Flow:**
 ```
 User says something project-related
-  → Agent checks local project state (ogp project query)
-  → Agent pings peer agents (ogp federation agent)
-  → Surfaces conflicts/info before starting
-  → Logs outcomes (ogp project contribute)
-  → Federation syncs to peers
+  → Agent may check local project state (ogp --for <framework> project query)
+  → Agent may ping relevant peer agents (ogp --for <framework> federation agent)
+  → Surfaces relevant conflicts/info before or during work
+  → Logs outcomes (ogp --for <framework> project contribute)
+  → Shares or queries peer context through project-aware federation flows when appropriate
 ```
 
 **The tool-agnostic principle:**
 The project doesn't care what tools you use. `context.notes`, `context.repository`, `context.tools` are just text. If you keep notes in Obsidian, that's in `context.notes`. If your peer uses GitHub wikis, that's in their `context.notes`. Peer agents read each other's context entries and know where to look — or know what to ask.
 
 **Storage:**
-- `~/.ogp/projects.json` — all project data and contributions
-- `~/.ogp/peers.json` — peer identities and federation state
+- `~/.ogp/projects.json` / `~/.ogp-hermes/projects.json` — project data and contributions per framework
+- `~/.ogp/peers.json` / `~/.ogp-hermes/peers.json` — peer identities and federation state per framework
+- `~/.ogp-meta/config.json` — enabled frameworks and default selection