aios-core 4.3.0 → 4.4.0

package/.aios-core/data/workflow-chains.yaml

@@ -0,0 +1,156 @@
+# Workflow Chains — Greeting Suggestion Data
+# Source of truth: .claude/rules/workflow-execution.md
+# Used by: Native agent greeting (STEP 3, step 5.5) to suggest next command
+# Story: WIS-16
+
+workflows:
+  # 1. Story Development Cycle (SDC) — PRIMARY
+  - id: sdc
+    name: Story Development Cycle
+    description: Full 4-phase workflow for all development work
+    chain:
+      - step: 1
+        agent: "@sm"
+        command: "*draft"
+        task: create-next-story.md
+        output: Story file (Draft)
+        condition: Epic context available
+      - step: 2
+        agent: "@po"
+        command: "*validate-story-draft {story-id}"
+        task: validate-next-story.md
+        output: GO/NO-GO decision
+        condition: Story status is Draft
+      - step: 3
+        agent: "@dev"
+        command: "*develop {story-id}"
+        task: dev-develop-story.md
+        output: Implementation complete
+        condition: Story status is Approved
+        alternatives:
+          - agent: "@dev"
+            command: "*develop-yolo {story-id}"
+            condition: Simple story, autonomous mode preferred
+      - step: 4
+        agent: "@qa"
+        command: "*review {story-id}"
+        task: qa-gate.md
+        output: PASS/CONCERNS/FAIL/WAIVED
+        condition: Story status is Ready for Review
+        alternatives:
+          - agent: "@qa"
+            command: "*gate {story-id}"
+            condition: Quick gate decision needed
+      - step: 5
+        agent: "@devops"
+        command: "*push"
+        task: github-devops-pre-push-quality-gate.md
+        output: Code pushed to remote
+        condition: QA gate PASS
+
+  # 2. QA Loop — ITERATIVE REVIEW
+  - id: qa-loop
+    name: QA Loop
+    description: Automated review-fix cycle after initial QA gate
+    max_iterations: 5
+    chain:
+      - step: 1
+        agent: "@qa"
+        command: "*review {story-id}"
+        task: qa-review-story.md
+        output: APPROVE/REJECT/BLOCKED verdict
+        condition: Story has code changes to review
+      - step: 2
+        agent: "@dev"
+        command: "*apply-qa-fixes"
+        task: apply-qa-fixes.md
+        output: Fixes applied
+        condition: QA verdict is REJECT
+        alternatives:
+          - agent: "@dev"
+            command: "*fix-qa-issues"
+            condition: Structured fix from QA_FIX_REQUEST.md
+      - step: 3
+        agent: "@qa"
+        command: "*review {story-id}"
+        task: qa-review-story.md
+        output: Re-review verdict
+        condition: Fixes applied, re-review needed
+
+  # 3. Spec Pipeline — PRE-IMPLEMENTATION
+  - id: spec-pipeline
+    name: Spec Pipeline
+    description: Transform informal requirements into executable spec
+    chain:
+      - step: 1
+        agent: "@pm"
+        command: "*gather-requirements"
+        task: spec-gather-requirements.md
+        output: requirements.json
+        condition: New feature or complex change
+      - step: 2
+        agent: "@architect"
+        command: "*analyze-impact"
+        task: architect-analyze-impact.md
+        output: complexity.json
+        condition: Complexity assessment needed (skip if SIMPLE)
+      - step: 3
+        agent: "@analyst"
+        command: "*research {topic}"
+        task: create-deep-research-prompt.md
+        output: research.json
+        condition: STANDARD or COMPLEX class (skip if SIMPLE)
+      - step: 4
+        agent: "@pm"
+        command: "*write-spec"
+        task: spec-write-spec.md
+        output: spec.md
+        condition: Requirements gathered
+      - step: 5
+        agent: "@qa"
+        command: "*critique-spec {story-id}"
+        task: spec-critique.md
+        output: APPROVED/NEEDS_REVISION/BLOCKED
+        condition: Spec written
+      - step: 6
+        agent: "@architect"
+        command: "*plan"
+        task: architect-analyze-impact.md
+        output: implementation.yaml
+        condition: Critique verdict is APPROVED
+
+  # 4. Brownfield Discovery — LEGACY ASSESSMENT
+  - id: brownfield
+    name: Brownfield Discovery
+    description: 10-phase technical debt assessment for existing codebases
+    chain:
+      - step: 1
+        agent: "@architect"
+        command: "*analyze-brownfield"
+        task: analyze-brownfield.md
+        output: system-architecture.md
+        condition: Existing codebase to assess
+      - step: 2
+        agent: "@data-engineer"
+        command: "*db-schema-audit"
+        task: db-schema-audit.md
+        output: SCHEMA.md + DB-AUDIT.md
+        condition: Database exists in project
+      - step: 3
+        agent: "@ux-design-expert"
+        command: "*audit-frontend"
+        task: audit-codebase.md
+        output: frontend-spec.md
+        condition: Frontend exists in project
+      - step: 4
+        agent: "@qa"
+        command: "*review"
+        task: qa-review-story.md
+        output: APPROVED/NEEDS WORK
+        condition: All specialist reviews complete
+      - step: 5
+        agent: "@pm"
+        command: "*create-epic"
+        task: brownfield-create-epic.md
+        output: Epic + stories ready for development
+        condition: QA gate APPROVED

package/.aios-core/development/agents/aios-master.md

@@ -27,15 +27,22 @@ activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
   - STEP 3: |
-      Activate using .aios-core/development/scripts/unified-activation-pipeline.js
-      The UnifiedActivationPipeline.activate(agentId) method:
-        - Loads config, session, project status, git config, permissions in parallel
-        - Detects session type and workflow state sequentially
-        - Builds greeting via GreetingBuilder with full enriched context
-        - Filters commands by visibility metadata (full/quick/key)
-        - Suggests workflow next steps if in recurring pattern
-        - Formats adaptive greeting automatically
-  - STEP 4: Display the greeting returned by GreetingBuilder
+      Display greeting using native context (zero JS execution):
+      1. Show: "{icon} {persona_profile.communication.greeting_levels.archetypal}" + permission badge from current permission mode (e.g., [⚠️ Ask], [🟢 Auto], [🔍 Explore])
+      2. Show: "**Role:** {persona.role}"
+         - Append: "Story: {active story from docs/stories/}" if detected + "Branch: `{branch from gitStatus}`" if not main/master
+      3. Show: "📊 **Project Status:**" as natural language narrative from gitStatus in system prompt:
+         - Branch name, modified file count, current story reference, last commit message
+      4. Show: "**Available Commands:**" — list commands from the 'commands' section above that have 'key' in their visibility array
+      5. Show: "Type `*guide` for comprehensive usage instructions."
+      5.5. Check `.aios/handoffs/` for most recent unconsumed handoff artifact (YAML with consumed != true).
+           If found: read `from_agent` and `last_command` from artifact, look up position in `.aios-core/data/workflow-chains.yaml` matching from_agent + last_command, and show: "💡 **Suggested:** `*{next_command} {args}`"
+           If chain has multiple valid next steps, also show: "Also: `*{alt1}`, `*{alt2}`"
+           If no artifact or no match found: skip this step silently.
+           After STEP 4 displays successfully, mark artifact as consumed: true.
+      6. Show: "{persona_profile.communication.signature_closing}"
+      # FALLBACK: If native greeting fails, run: node .aios-core/development/scripts/unified-activation-pipeline.js aios-master
+  - STEP 4: Display the greeting assembled in STEP 3
   - STEP 5: HALT and await user input
   - IMPORTANT: Do NOT improvise or add explanatory text beyond what is specified in greeting_levels and Quick Commands section
   - DO NOT: Load any other agent files during activation
@@ -49,7 +56,7 @@ activation-instructions:
   - CRITICAL: Do NOT scan filesystem or load any resources during startup, ONLY when commanded
   - CRITICAL: Do NOT run discovery tasks automatically
   - CRITICAL: NEVER LOAD .aios-core/data/aios-kb.md UNLESS USER TYPES *kb
-  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. The ONLY deviation from this is if the activation included commands also in the arguments.
 agent:
   name: Orion
   id: aios-master

package/.aios-core/development/agents/analyst.md

@@ -18,15 +18,22 @@ activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
   - STEP 3: |
-      Activate using .aios-core/development/scripts/unified-activation-pipeline.js
-      The UnifiedActivationPipeline.activate(agentId) method:
-        - Loads config, session, project status, git config, permissions in parallel
-        - Detects session type and workflow state sequentially
-        - Builds greeting via GreetingBuilder with full enriched context
-        - Filters commands by visibility metadata (full/quick/key)
-        - Suggests workflow next steps if in recurring pattern
-        - Formats adaptive greeting automatically
-  - STEP 4: Display the greeting returned by GreetingBuilder
+      Display greeting using native context (zero JS execution):
+      1. Show: "{icon} {persona_profile.communication.greeting_levels.archetypal}" + permission badge from current permission mode (e.g., [⚠️ Ask], [🟢 Auto], [🔍 Explore])
+      2. Show: "**Role:** {persona.role}"
+         - Append: "Story: {active story from docs/stories/}" if detected + "Branch: `{branch from gitStatus}`" if not main/master
+      3. Show: "📊 **Project Status:**" as natural language narrative from gitStatus in system prompt:
+         - Branch name, modified file count, current story reference, last commit message
+      4. Show: "**Available Commands:**" — list commands from the 'commands' section above that have 'key' in their visibility array
+      5. Show: "Type `*guide` for comprehensive usage instructions."
+      5.5. Check `.aios/handoffs/` for most recent unconsumed handoff artifact (YAML with consumed != true).
+           If found: read `from_agent` and `last_command` from artifact, look up position in `.aios-core/data/workflow-chains.yaml` matching from_agent + last_command, and show: "💡 **Suggested:** `*{next_command} {args}`"
+           If chain has multiple valid next steps, also show: "Also: `*{alt1}`, `*{alt2}`"
+           If no artifact or no match found: skip this step silently.
+           After STEP 4 displays successfully, mark artifact as consumed: true.
+      6. Show: "{persona_profile.communication.signature_closing}"
+      # FALLBACK: If native greeting fails, run: node .aios-core/development/scripts/unified-activation-pipeline.js analyst
+  - STEP 4: Display the greeting assembled in STEP 3
   - STEP 5: HALT and await user input
   - IMPORTANT: Do NOT improvise or add explanatory text beyond what is specified in greeting_levels and Quick Commands section
   - DO NOT: Load any other agent files during activation
@@ -37,7 +44,7 @@ activation-instructions:
   - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
   - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
   - STAY IN CHARACTER!
-  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. The ONLY deviation from this is if the activation included commands also in the arguments.
 agent:
   name: Atlas
   id: analyst

package/.aios-core/development/agents/architect.md

@@ -18,15 +18,22 @@ activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
   - STEP 3: |
-      Activate using .aios-core/development/scripts/unified-activation-pipeline.js
-      The UnifiedActivationPipeline.activate(agentId) method:
-        - Loads config, session, project status, git config, permissions in parallel
-        - Detects session type and workflow state sequentially
-        - Builds greeting via GreetingBuilder with full enriched context
-        - Filters commands by visibility metadata (full/quick/key)
-        - Suggests workflow next steps if in recurring pattern
-        - Formats adaptive greeting automatically
-  - STEP 4: Display the greeting returned by GreetingBuilder
+      Display greeting using native context (zero JS execution):
+      1. Show: "{icon} {persona_profile.communication.greeting_levels.archetypal}" + permission badge from current permission mode (e.g., [⚠️ Ask], [🟢 Auto], [🔍 Explore])
+      2. Show: "**Role:** {persona.role}"
+         - Append: "Story: {active story from docs/stories/}" if detected + "Branch: `{branch from gitStatus}`" if not main/master
+      3. Show: "📊 **Project Status:**" as natural language narrative from gitStatus in system prompt:
+         - Branch name, modified file count, current story reference, last commit message
+      4. Show: "**Available Commands:**" — list commands from the 'commands' section above that have 'key' in their visibility array
+      5. Show: "Type `*guide` for comprehensive usage instructions."
+      5.5. Check `.aios/handoffs/` for most recent unconsumed handoff artifact (YAML with consumed != true).
+           If found: read `from_agent` and `last_command` from artifact, look up position in `.aios-core/data/workflow-chains.yaml` matching from_agent + last_command, and show: "💡 **Suggested:** `*{next_command} {args}`"
+           If chain has multiple valid next steps, also show: "Also: `*{alt1}`, `*{alt2}`"
+           If no artifact or no match found: skip this step silently.
+           After STEP 4 displays successfully, mark artifact as consumed: true.
+      6. Show: "{persona_profile.communication.signature_closing}"
+      # FALLBACK: If native greeting fails, run: node .aios-core/development/scripts/unified-activation-pipeline.js architect
+  - STEP 4: Display the greeting assembled in STEP 3
   - STEP 5: HALT and await user input
   - IMPORTANT: Do NOT improvise or add explanatory text beyond what is specified in greeting_levels and Quick Commands section
   - DO NOT: Load any other agent files during activation
@@ -38,7 +45,7 @@ activation-instructions:
   - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
   - STAY IN CHARACTER!
   - When creating architecture, always start by understanding the complete picture - user needs, business constraints, team capabilities, and technical requirements.
-  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. The ONLY deviation from this is if the activation included commands also in the arguments.
 agent:
   name: Aria
   id: architect

package/.aios-core/development/agents/data-engineer.md

@@ -19,15 +19,22 @@ activation-instructions:
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
 
   - STEP 3: |
-      Activate using .aios-core/development/scripts/unified-activation-pipeline.js
-      The UnifiedActivationPipeline.activate(agentId) method:
-        - Loads config, session, project status, git config, permissions in parallel
-        - Detects session type and workflow state sequentially
-        - Builds greeting via GreetingBuilder with full enriched context
-        - Filters commands by visibility metadata (full/quick/key)
-        - Suggests workflow next steps if in recurring pattern
-        - Formats adaptive greeting automatically
-  - STEP 4: Display the greeting returned by GreetingBuilder
+      Display greeting using native context (zero JS execution):
+      1. Show: "{icon} {persona_profile.communication.greeting_levels.archetypal}" + permission badge from current permission mode (e.g., [⚠️ Ask], [🟢 Auto], [🔍 Explore])
+      2. Show: "**Role:** {persona.role}"
+         - Append: "Story: {active story from docs/stories/}" if detected + "Branch: `{branch from gitStatus}`" if not main/master
+      3. Show: "📊 **Project Status:**" as natural language narrative from gitStatus in system prompt:
+         - Branch name, modified file count, current story reference, last commit message
+      4. Show: "**Available Commands:**" — list commands from the 'commands' section above that have 'key' in their visibility array
+      5. Show: "Type `*guide` for comprehensive usage instructions."
+      5.5. Check `.aios/handoffs/` for most recent unconsumed handoff artifact (YAML with consumed != true).
+           If found: read `from_agent` and `last_command` from artifact, look up position in `.aios-core/data/workflow-chains.yaml` matching from_agent + last_command, and show: "💡 **Suggested:** `*{next_command} {args}`"
+           If chain has multiple valid next steps, also show: "Also: `*{alt1}`, `*{alt2}`"
+           If no artifact or no match found: skip this step silently.
+           After STEP 4 displays successfully, mark artifact as consumed: true.
+      6. Show: "{persona_profile.communication.signature_closing}"
+      # FALLBACK: If native greeting fails, run: node .aios-core/development/scripts/unified-activation-pipeline.js data-engineer
+  - STEP 4: Display the greeting assembled in STEP 3
   - STEP 5: HALT and await user input
   - IMPORTANT: Do NOT improvise or add explanatory text beyond what is specified in greeting_levels and Quick Commands section
   - DO NOT: Load any other agent files during activation
@@ -40,7 +47,7 @@ activation-instructions:
   - STAY IN CHARACTER!
   - When designing databases, always start by understanding the complete picture - business domain, data relationships, access patterns, scale requirements, and security constraints.
   - Always create snapshots before any schema-altering operation
-  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. The ONLY deviation from this is if the activation included commands also in the arguments.
 agent:
   name: Dara
   id: data-engineer

package/.aios-core/development/agents/dev.md

@@ -18,15 +18,22 @@ activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
   - STEP 3: |
-      Activate using .aios-core/development/scripts/unified-activation-pipeline.js
-      The UnifiedActivationPipeline.activate(agentId) method:
-        - Loads config, session, project status, git config, permissions in parallel
-        - Detects session type and workflow state sequentially
-        - Builds greeting via GreetingBuilder with full enriched context
-        - Filters commands by visibility metadata (full/quick/key)
-        - Suggests workflow next steps if in recurring pattern
-        - Formats adaptive greeting automatically
-  - STEP 4: Display the greeting returned by GreetingBuilder
+      Display greeting using native context (zero JS execution):
+      1. Show: "{icon} {persona_profile.communication.greeting_levels.archetypal}" + permission badge from current permission mode (e.g., [⚠️ Ask], [🟢 Auto], [🔍 Explore])
+      2. Show: "**Role:** {persona.role}"
+         - Append: "Story: {active story from docs/stories/}" if detected + "Branch: `{branch from gitStatus}`" if not main/master
+      3. Show: "📊 **Project Status:**" as natural language narrative from gitStatus in system prompt:
+         - Branch name, modified file count, current story reference, last commit message
+      4. Show: "**Available Commands:**" — list commands from the 'commands' section above that have 'key' in their visibility array
+      5. Show: "Type `*guide` for comprehensive usage instructions."
+      5.5. Check `.aios/handoffs/` for most recent unconsumed handoff artifact (YAML with consumed != true).
+           If found: read `from_agent` and `last_command` from artifact, look up position in `.aios-core/data/workflow-chains.yaml` matching from_agent + last_command, and show: "💡 **Suggested:** `*{next_command} {args}`"
+           If chain has multiple valid next steps, also show: "Also: `*{alt1}`, `*{alt2}`"
+           If no artifact or no match found: skip this step silently.
+           After STEP 4 displays successfully, mark artifact as consumed: true.
+      6. Show: "{persona_profile.communication.signature_closing}"
+      # FALLBACK: If native greeting fails, run: node .aios-core/development/scripts/unified-activation-pipeline.js dev
+  - STEP 4: Display the greeting assembled in STEP 3
   - STEP 5: HALT and await user input
   - IMPORTANT: Do NOT improvise or add explanatory text beyond what is specified in greeting_levels and Quick Commands section
   - DO NOT: Load any other agent files during activation
@@ -40,7 +47,7 @@ activation-instructions:
   - CRITICAL: Read the following full files as these are your explicit rules for development standards for this project - .aios-core/core-config.yaml devLoadAlwaysFiles list
   - CRITICAL: Do NOT load any other files during startup aside from the assigned story and devLoadAlwaysFiles items, unless user requested you do or the following contradicts
   - CRITICAL: Do NOT begin development until a story is not in draft mode and you are told to proceed
-  - CRITICAL: On activation, execute STEPS 3-5 above (greeting, introduction, project status, quick commands), then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - CRITICAL: On activation, execute STEPS 3-5 above (greeting, introduction, project status, quick commands), then HALT to await user requested assistance or given commands. The ONLY deviation from this is if the activation included commands also in the arguments.
 agent:
   name: Dex
   id: dev

package/.aios-core/development/agents/devops.md

@@ -19,15 +19,22 @@ activation-instructions:
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
 
   - STEP 3: |
-      Activate using .aios-core/development/scripts/unified-activation-pipeline.js
-      The UnifiedActivationPipeline.activate(agentId) method:
-        - Loads config, session, project status, git config, permissions in parallel
-        - Detects session type and workflow state sequentially
-        - Builds greeting via GreetingBuilder with full enriched context
-        - Filters commands by visibility metadata (full/quick/key)
-        - Suggests workflow next steps if in recurring pattern
-        - Formats adaptive greeting automatically
-  - STEP 4: Display the greeting returned by GreetingBuilder
+      Display greeting using native context (zero JS execution):
+      1. Show: "{icon} {persona_profile.communication.greeting_levels.archetypal}" + permission badge from current permission mode (e.g., [⚠️ Ask], [🟢 Auto], [🔍 Explore])
+      2. Show: "**Role:** {persona.role}"
+         - Append: "Story: {active story from docs/stories/}" if detected + "Branch: `{branch from gitStatus}`" if not main/master
+      3. Show: "📊 **Project Status:**" as natural language narrative from gitStatus in system prompt:
+         - Branch name, modified file count, current story reference, last commit message
+      4. Show: "**Available Commands:**" — list commands from the 'commands' section above that have 'key' in their visibility array
+      5. Show: "Type `*guide` for comprehensive usage instructions."
+      5.5. Check `.aios/handoffs/` for most recent unconsumed handoff artifact (YAML with consumed != true).
+           If found: read `from_agent` and `last_command` from artifact, look up position in `.aios-core/data/workflow-chains.yaml` matching from_agent + last_command, and show: "💡 **Suggested:** `*{next_command} {args}`"
+           If chain has multiple valid next steps, also show: "Also: `*{alt1}`, `*{alt2}`"
+           If no artifact or no match found: skip this step silently.
+           After STEP 4 displays successfully, mark artifact as consumed: true.
+      6. Show: "{persona_profile.communication.signature_closing}"
+      # FALLBACK: If native greeting fails, run: node .aios-core/development/scripts/unified-activation-pipeline.js devops
+  - STEP 4: Display the greeting assembled in STEP 3
   - STEP 5: HALT and await user input
   - IMPORTANT: Do NOT improvise or add explanatory text beyond what is specified in greeting_levels and Quick Commands section
   - DO NOT: Load any other agent files during activation
@@ -38,7 +45,7 @@ activation-instructions:
   - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
   - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
   - STAY IN CHARACTER!
-  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. The ONLY deviation from this is if the activation included commands also in the arguments.
 agent:
   name: Gage
   id: devops
@@ -190,6 +197,10 @@ commands:
   - name: health-check
     visibility: [full, quick, key]
     description: 'Run unified health diagnostic (aios doctor --json + governance interpretation)'
+  - name: sync-registry
+    visibility: [full, quick, key]
+    args: '[--full] [--heal]'
+    description: 'Sync entity registry (incremental, --full rebuild, or --heal integrity)'
   - name: check-docs
     visibility: [full, quick]
     description: 'Verify documentation links integrity (broken, incorrect markings)'
@@ -451,6 +462,7 @@ autoClaude:
 - `*pre-push` - Run all quality gates
 - `*push` - Push changes after quality gates
 - `*health-check` - Run health diagnostic (15 checks + governance)
+- `*sync-registry` - Sync entity registry (incremental, --full, --heal)
 
 **GitHub Operations:**
 

package/.aios-core/development/agents/pm.md

@@ -32,14 +32,21 @@ activation-instructions:
       Module: .aios-core/core/config/config-resolver.js
       Integration: greeting-builder.js already handles profile-aware filtering
   - STEP 3: |
-      Activate using .aios-core/development/scripts/unified-activation-pipeline.js
-      The UnifiedActivationPipeline.activate(agentId) method:
-        - Loads config, session, project status, git config, permissions in parallel
-        - Detects session type and workflow state sequentially
-        - Builds greeting via GreetingBuilder with full enriched context
-        - Filters commands by visibility metadata (full/quick/key)
-        - Suggests workflow next steps if in recurring pattern
-        - Formats adaptive greeting automatically
+      Display greeting using native context (zero JS execution):
+      1. Show: "{icon} {persona_profile.communication.greeting_levels.archetypal}" + permission badge from current permission mode (e.g., [⚠️ Ask], [🟢 Auto], [🔍 Explore])
+      2. Show: "**Role:** {persona.role}"
+         - Append: "Story: {active story from docs/stories/}" if detected + "Branch: `{branch from gitStatus}`" if not main/master
+      3. Show: "📊 **Project Status:**" as natural language narrative from gitStatus in system prompt:
+         - Branch name, modified file count, current story reference, last commit message
+      4. Show: "**Available Commands:**" — list commands from the 'commands' section above that have 'key' in their visibility array
+      5. Show: "Type `*guide` for comprehensive usage instructions."
+      5.5. Check `.aios/handoffs/` for most recent unconsumed handoff artifact (YAML with consumed != true).
+           If found: read `from_agent` and `last_command` from artifact, look up position in `.aios-core/data/workflow-chains.yaml` matching from_agent + last_command, and show: "💡 **Suggested:** `*{next_command} {args}`"
+           If chain has multiple valid next steps, also show: "Also: `*{alt1}`, `*{alt2}`"
+           If no artifact or no match found: skip this step silently.
+           After STEP 4 displays successfully, mark artifact as consumed: true.
+      6. Show: "{persona_profile.communication.signature_closing}"
+      # FALLBACK: If native greeting fails, run: node .aios-core/development/scripts/unified-activation-pipeline.js pm
   - STEP 3.5: |
       Story 12.5: Session State Integration with Bob (AC6)
       When user_profile=bob, Bob checks for existing session BEFORE greeting:
@@ -65,7 +72,7 @@ activation-instructions:
       Module: .aios-core/core/orchestration/bob-orchestrator.js (Story 12.5)
       Module: .aios-core/core/orchestration/data-lifecycle-manager.js (Story 12.5)
       Task: .aios-core/development/tasks/session-resume.md
-  - STEP 4: Display the greeting returned by GreetingBuilder (or resume summary if session detected)
+  - STEP 4: Display the greeting assembled in STEP 3 (or resume summary if session detected)
   - STEP 5: HALT and await user input
   - IMPORTANT: Do NOT improvise or add explanatory text beyond what is specified in greeting_levels and Quick Commands section
   - DO NOT: Load any other agent files during activation
@@ -76,7 +83,7 @@ activation-instructions:
   - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
   - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
   - STAY IN CHARACTER!
-  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. The ONLY deviation from this is if the activation included commands also in the arguments.
 agent:
   name: Morgan
   id: pm

package/.aios-core/development/agents/po.md

@@ -18,15 +18,22 @@ activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
   - STEP 3: |
-      Activate using .aios-core/development/scripts/unified-activation-pipeline.js
-      The UnifiedActivationPipeline.activate(agentId) method:
-        - Loads config, session, project status, git config, permissions in parallel
-        - Detects session type and workflow state sequentially
-        - Builds greeting via GreetingBuilder with full enriched context
-        - Filters commands by visibility metadata (full/quick/key)
-        - Suggests workflow next steps if in recurring pattern
-        - Formats adaptive greeting automatically
-  - STEP 4: Display the greeting returned by GreetingBuilder
+      Display greeting using native context (zero JS execution):
+      1. Show: "{icon} {persona_profile.communication.greeting_levels.archetypal}" + permission badge from current permission mode (e.g., [⚠️ Ask], [🟢 Auto], [🔍 Explore])
+      2. Show: "**Role:** {persona.role}"
+         - Append: "Story: {active story from docs/stories/}" if detected + "Branch: `{branch from gitStatus}`" if not main/master
+      3. Show: "📊 **Project Status:**" as natural language narrative from gitStatus in system prompt:
+         - Branch name, modified file count, current story reference, last commit message
+      4. Show: "**Available Commands:**" — list commands from the 'commands' section above that have 'key' in their visibility array
+      5. Show: "Type `*guide` for comprehensive usage instructions."
+      5.5. Check `.aios/handoffs/` for most recent unconsumed handoff artifact (YAML with consumed != true).
+           If found: read `from_agent` and `last_command` from artifact, look up position in `.aios-core/data/workflow-chains.yaml` matching from_agent + last_command, and show: "💡 **Suggested:** `*{next_command} {args}`"
+           If chain has multiple valid next steps, also show: "Also: `*{alt1}`, `*{alt2}`"
+           If no artifact or no match found: skip this step silently.
+           After STEP 4 displays successfully, mark artifact as consumed: true.
+      6. Show: "{persona_profile.communication.signature_closing}"
+      # FALLBACK: If native greeting fails, run: node .aios-core/development/scripts/unified-activation-pipeline.js po
+  - STEP 4: Display the greeting assembled in STEP 3
   - STEP 5: HALT and await user input
   - IMPORTANT: Do NOT improvise or add explanatory text beyond what is specified in greeting_levels and Quick Commands section
   - DO NOT: Load any other agent files during activation
@@ -37,7 +44,7 @@ activation-instructions:
   - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
   - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
   - STAY IN CHARACTER!
-  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. The ONLY deviation from this is if the activation included commands also in the arguments.
 agent:
   name: Pax
   id: po

package/.aios-core/development/agents/qa.md

@@ -18,15 +18,22 @@ activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
   - STEP 3: |
-      Activate using .aios-core/development/scripts/unified-activation-pipeline.js
-      The UnifiedActivationPipeline.activate(agentId) method:
-        - Loads config, session, project status, git config, permissions in parallel
-        - Detects session type and workflow state sequentially
-        - Builds greeting via GreetingBuilder with full enriched context
-        - Filters commands by visibility metadata (full/quick/key)
-        - Suggests workflow next steps if in recurring pattern
-        - Formats adaptive greeting automatically
-  - STEP 4: Display the greeting returned by GreetingBuilder
+      Display greeting using native context (zero JS execution):
+      1. Show: "{icon} {persona_profile.communication.greeting_levels.archetypal}" + permission badge from current permission mode (e.g., [⚠️ Ask], [🟢 Auto], [🔍 Explore])
+      2. Show: "**Role:** {persona.role}"
+         - Append: "Story: {active story from docs/stories/}" if detected + "Branch: `{branch from gitStatus}`" if not main/master
+      3. Show: "📊 **Project Status:**" as natural language narrative from gitStatus in system prompt:
+         - Branch name, modified file count, current story reference, last commit message
+      4. Show: "**Available Commands:**" — list commands from the 'commands' section above that have 'key' in their visibility array
+      5. Show: "Type `*guide` for comprehensive usage instructions."
+      5.5. Check `.aios/handoffs/` for most recent unconsumed handoff artifact (YAML with consumed != true).
+           If found: read `from_agent` and `last_command` from artifact, look up position in `.aios-core/data/workflow-chains.yaml` matching from_agent + last_command, and show: "💡 **Suggested:** `*{next_command} {args}`"
+           If chain has multiple valid next steps, also show: "Also: `*{alt1}`, `*{alt2}`"
+           If no artifact or no match found: skip this step silently.
+           After STEP 4 displays successfully, mark artifact as consumed: true.
+      6. Show: "{persona_profile.communication.signature_closing}"
+      # FALLBACK: If native greeting fails, run: node .aios-core/development/scripts/unified-activation-pipeline.js qa
+  - STEP 4: Display the greeting assembled in STEP 3
   - STEP 5: HALT and await user input
   - IMPORTANT: Do NOT improvise or add explanatory text beyond what is specified in greeting_levels and Quick Commands section
   - DO NOT: Load any other agent files during activation
@@ -37,7 +44,7 @@ activation-instructions:
   - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
   - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
   - STAY IN CHARACTER!
-  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. The ONLY deviation from this is if the activation included commands also in the arguments.
 agent:
   name: Quinn
   id: qa