aios-core 4.3.0 → 4.4.0

package/.aios-core/development/agents/sm.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 sm
+  - 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: River
   id: sm

package/.aios-core/development/agents/squad-creator.md

@@ -18,25 +18,34 @@ 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
+      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 squad-creator
         - Formats adaptive greeting automatically
-  - STEP 4: Display the greeting returned by GreetingBuilder
+  - STEP 4: Greeting already rendered inline in STEP 3 — proceed to STEP 5
   - 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
   - ONLY load dependency files when user selects them for execution via command or request of a task
+  - EXCEPTION: STEP 5.5 may read `.aios/handoffs/` and `.aios-core/data/workflow-chains.yaml` during activation
   - The agent.customization field ALWAYS takes precedence over any conflicting instructions
   - CRITICAL WORKFLOW RULE: When executing tasks from dependencies, follow task instructions exactly as written - they are executable workflows, not reference material
   - MANDATORY INTERACTION RULE: Tasks with elicit=true require user interaction using exact specified format - never skip elicitation for efficiency
   - When listing tasks/templates or presenting options during conversations, always show as numbered options list
   - STAY IN CHARACTER!
-  - CRITICAL: On activation, execute STEPS 3-5 above (greeting, introduction, project status, quick commands), then HALT to await user requested assistance
+  - 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: Craft
   id: squad-creator

package/.aios-core/development/agents/ux-design-expert.md

@@ -23,15 +23,22 @@ activation-instructions:
   - STEP 2: Adopt the hybrid persona (Sally + Brad Frost)
 
   - 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 ux-design-expert
+  - STEP 4: Greeting already rendered inline in STEP 3 — proceed to STEP 5
   - 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

package/.aios-core/development/tasks/apply-qa-fixes.md

@@ -338,3 +338,10 @@ This task is complete when:
 - ✅ All tests pass (linting, unit, integration)
 - ✅ Story file is updated with changes
 - ✅ Code is ready for QA re-review
+
+## Handoff
+next_agent: @qa
+next_command: *review {story-id}
+condition: Fixes applied, ready for re-review
+alternatives:
+  - agent: @dev, command: *run-tests, condition: Need to verify fixes pass tests first

package/.aios-core/development/tasks/architect-analyze-impact.md

@@ -824,4 +824,11 @@ module.exports = AnalyzeImpactTask;
 - Sanitize component paths and modification descriptions
 - Ensure approval workflow cannot be bypassed for critical changes
 - Validate output file paths for report generation
-- Log all high-risk modification attempts for audit 
+- Log all high-risk modification attempts for audit
+
+## Handoff
+next_agent: @analyst
+next_command: *research {topic}
+condition: Complexity class is STANDARD or COMPLEX (research needed)
+alternatives:
+  - agent: @pm, command: *write-spec, condition: Complexity class is SIMPLE (skip research) 

package/.aios-core/development/tasks/brownfield-create-story.md

@@ -354,4 +354,11 @@ The story creation is successful when:
 - Always prioritize existing system integrity
 - When in doubt about integration complexity, use brownfield-create-epic instead
 - Stories should take no more than 4 hours of focused development work
+
+## Handoff
+next_agent: @po
+next_command: *validate-story-draft {story-id}
+condition: Brownfield story created from assessment
+alternatives:
+  - agent: @sm, command: *draft, condition: Need additional stories from same assessment
  

package/.aios-core/development/tasks/build-autonomous.md

@@ -190,3 +190,10 @@ The AutonomousBuildLoop emits these events for monitoring:
 ---
 
 _Task file for Story 8.1 - Coder Agent Loop_
+
+## Handoff
+next_agent: @qa
+next_command: *review {story-id}
+condition: Autonomous build completed successfully
+alternatives:
+  - agent: @dev, command: *build-resume {story-id}, condition: Build failed, needs resume

package/.aios-core/development/tasks/create-deep-research-prompt.md

@@ -496,4 +496,11 @@ CRITICAL: collaborate with the user to develop specific, actionable research que
 - Balance comprehensiveness with focus
 - Document assumptions and limitations clearly
 - Plan for iterative refinement based on initial findings
+
+## Handoff
+next_agent: @pm
+next_command: *write-spec
+condition: Research complete (research.json created)
+alternatives:
+  - agent: @architect, command: *analyze-impact, condition: Research reveals higher complexity than expected
  

package/.aios-core/development/tasks/create-next-story.md

@@ -782,3 +782,10 @@ Use the primary agent from "Specialized Agent Assignment" to determine which sel
   - Next steps: For Complex stories, suggest the user carefully review the story draft and also optionally have the PO run the task `aios-core/tasks/validate-next-story`
 
 **ClickUp Integration Note:** This task now includes Epic verification (Section 5.1), ClickUp story task creation (Section 5.3), and automatic frontmatter updates (Section 5.4). Stories are created as subtasks of their parent Epic in ClickUp's Backlog list. If Epic verification or ClickUp sync fails, the story file will still be created locally with a warning message.
+
+## Handoff
+next_agent: @po
+next_command: *validate-story-draft {story-id}
+condition: Story status is Draft
+alternatives:
+  - agent: @dev, command: *develop {story-id}, condition: Story already validated by PO

package/.aios-core/development/tasks/create-suite.md

@@ -281,4 +281,11 @@ Creates multiple related components in a single batch operation with dependency
 - Supports atomic creation (all or nothing)
 - Transaction log enables rollback functionality
 - Dependency resolution ensures correct creation order
+
+## Handoff
+next_agent: @dev
+next_command: *run-tests
+condition: Test suite created, ready for execution
+alternatives:
+  - agent: @qa, command: *review {story-id}, condition: Tests written as part of review
 - Preview functionality helps prevent mistakes 

package/.aios-core/development/tasks/dev-develop-story.md

@@ -914,3 +914,11 @@ Found 5 technical decisions needed.
 - **Decision Logs**: Persisted in `.ai/decision-log-{story-id}.md` for future reference and review
 - **Educational Value**: Interactive mode explanations help developers learn framework patterns
 - **Scope Drift Prevention**: Pre-flight mode eliminates mid-development ambiguity
+
+## Handoff
+next_agent: @qa
+next_command: *review {story-id}
+condition: Story status is Ready for Review
+alternatives:
+  - agent: @qa, command: *gate {story-id}, condition: Quick gate decision needed
+  - agent: @dev, command: *apply-qa-fixes, condition: Self-identified issues during dev

package/.aios-core/development/tasks/execute-checklist.md

@@ -299,3 +299,10 @@ The LLM will:
 - Execute the complete checklist validation
 - Present a final report with pass/fail rates and key findings
 - Offer to provide detailed analysis of any section, especially those with warnings or failures
+
+## Handoff
+next_agent: @qa
+next_command: *review {story-id}
+condition: Checklist completed with all items passing
+alternatives:
+  - agent: @dev, command: *develop {story-id}, condition: Checklist found blocking issues

package/.aios-core/development/tasks/github-devops-github-pr-automation.md

@@ -711,3 +711,10 @@ github:
 - Gracefully handles missing story file
 - Uses GitHub CLI for reliability
 - Repository context from detector
+
+## Handoff
+next_agent: @po
+next_command: *close-story {story-id}
+condition: PR merged successfully
+alternatives:
+  - agent: @dev, command: *apply-qa-fixes, condition: PR review requested changes

package/.aios-core/development/tasks/github-devops-pre-push-quality-gate.md

@@ -851,3 +851,10 @@ Called via `@github-devops *pre-push` command.
 - Security scan is mandatory (TR-3.14.11)
 - User always has final approval
 - Detailed logging for troubleshooting
+
+## Handoff
+next_agent: @devops
+next_command: *push
+condition: All quality checks PASS
+alternatives:
+  - agent: @dev, command: *run-tests, condition: Quality checks FAIL, needs fixes

package/.aios-core/development/tasks/po-close-story.md

@@ -425,3 +425,10 @@ updated_at: 2026-02-05
 - `validate-next-story.md` - Validates story before implementation (START)
 - `po-close-story.md` - Closes story after merge (END)
 - `po-backlog-review.md` - Review backlog for sprint planning
+
+## Handoff
+next_agent: @sm
+next_command: *draft
+condition: Story closed, next story in epic available
+alternatives:
+  - agent: @po, command: *backlog-review, condition: Sprint review needed before next story

package/.aios-core/development/tasks/qa-create-fix-request.md

@@ -621,3 +621,10 @@ This task is complete when:
 - Constraints section present
 - File follows template structure
 ```
+
+## Handoff
+next_agent: @dev
+next_command: *fix-qa-issues
+condition: QA_FIX_REQUEST.md generated
+alternatives:
+  - agent: @dev, command: *apply-qa-fixes, condition: Simple fixes, no structured request needed

package/.aios-core/development/tasks/qa-fix-issues.md

@@ -683,3 +683,10 @@ metadata:
     - quality-assurance
     - development
 ```
+
+## Handoff
+next_agent: @qa
+next_command: *review {story-id}
+condition: All QA_FIX_REQUEST issues resolved
+alternatives:
+  - agent: @dev, command: *run-tests, condition: Verify fixes pass before re-review

package/.aios-core/development/tasks/qa-gate.md

@@ -419,4 +419,12 @@ Gate: CONCERNS → qa.qaLocation/gates/{epic}.{story}-{slug}.yml
 - Always write to standard path
 - Always update story with gate reference
 - Clear, actionable findings
+
+## Handoff
+next_agent: @devops
+next_command: *push
+condition: QA gate verdict is PASS
+alternatives:
+  - agent: @dev, command: *apply-qa-fixes, condition: QA gate verdict is FAIL or CONCERNS
+  - agent: @po, command: *close-story {story-id}, condition: QA gate verdict is WAIVED
  

package/.aios-core/development/tasks/qa-review-story.md

@@ -703,4 +703,12 @@ After review:
 
 - **No Action Required**: The sync happens transparently when using story-manager utilities. If sync fails, story file is still saved locally with a warning message.
 
+## Handoff
+next_agent: @dev
+next_command: *apply-qa-fixes
+condition: QA verdict is REJECT
+alternatives:
+  - agent: @devops, command: *push, condition: QA verdict is APPROVE
+  - agent: @dev, command: *fix-qa-issues, condition: Structured fix from QA_FIX_REQUEST.md
+
 - **Manual Sync**: If needed, use: `npm run sync-story -- --story {epic}.{story}` 

package/.aios-core/development/tasks/release-management.md

@@ -750,3 +750,10 @@ Migration: Replace /v1/users with /v2/users in API calls.
 
 - `ci-cd-configuration` - Set up CI to run before releases
 - `pr-automation` - Help users create PRs with proper commit formats
+
+## Handoff
+next_agent: @po
+next_command: *close-story {story-id}
+condition: Release published successfully
+alternatives:
+  - agent: @devops, command: *cleanup, condition: Post-release branch cleanup needed

package/.aios-core/development/tasks/spec-critique.md

@@ -593,3 +593,11 @@ metadata:
     - quality-gate
     - qa
 ```
+
+## Handoff
+next_agent: @architect
+next_command: *plan
+condition: Critique verdict is APPROVED
+alternatives:
+  - agent: @pm, command: *write-spec, condition: Critique verdict is NEEDS_REVISION
+  - agent: @architect, command: *analyze-impact, condition: Critique verdict is BLOCKED

package/.aios-core/development/tasks/spec-gather-requirements.md

@@ -543,3 +543,10 @@ metadata:
     - sdd-adoption
   inspiration: GitHub Spec-Kit 9-category taxonomy
 ```
+
+## Handoff
+next_agent: @architect
+next_command: *analyze-impact
+condition: Requirements gathered (requirements.json created)
+alternatives:
+  - agent: @pm, command: *write-spec, condition: SIMPLE complexity, skip assessment

package/.aios-core/development/tasks/spec-write-spec.md

@@ -529,3 +529,8 @@ metadata:
     - documentation
     - prompt-engineering
 ```
+
+## Handoff
+next_agent: @qa
+next_command: *critique-spec {story-id}
+condition: Spec written (spec.md created)

package/.aios-core/development/tasks/validate-next-story.md

@@ -462,4 +462,11 @@ Provide a structured validation report including:
 - **NO-GO**: Story requires fixes before implementation
 - **Implementation Readiness Score**: 1-10 scale
 - **Confidence Level**: High/Medium/Low for successful implementation
+
+## Handoff
+next_agent: @dev
+next_command: *develop {story-id}
+condition: Story status is Approved (GO decision)
+alternatives:
+  - agent: @sm, command: *draft, condition: Story rejected (NO-GO), needs rework