saravanakumardb1 f18134c719 docs: align ecosystem docs with single-source-of-truth agent pattern

Followup to single-source-of-truth migration. Active docs that taught or
described the old 8-file agent-config pattern are updated to reflect the
new architecture.

- docs/ECOSYSTEM_CONSISTENCY_AUDIT.md: update §7 Agent Documentation,
  resolve F19 (ActionTrail missing CLAUDE.md) and F20 (Auth App missing
  agent docs) — both eliminated by the migration. Update §9 consistency
  checklist with new file inventory (AGENTS.md + canonical pointer,
  thin copilot pointer, legacy files removed across all 17 active repos).

- docs/learning_ai_common_plat_INVENTORY.md: replace deleted
  AI.dev/SKILLS/update-agent-docs.md with agent-behavior-guidelines.md
  and agent-onboarding.md entries. Add check-agent-docs-drift.sh to the
  scripts table.

- docs/guides/PLATFORM_PLAYBOOK.md: update new-product scaffold tree to
  show the 4 canonical files (AGENTS.md + 3 auto-generated derivatives),
  drop CLAUDE.md/.cursorrules/.windsurfrules.

- docs/guides/PLATFORM_ACCELERATION_IDEAS.md: update create-app CLI
  description to reference the canonical pointer + derived files.

- docs/guides/WORKFLOW_SYNC.md: clarify what /repo_update-agent-docs does.

Historical/completed roadmaps in docs/roadmaps/completed/ are left as-is —
they accurately describe state at the time and editing them would rewrite
history.

2026-05-23 12:07:58 -07:00

6.2 KiB

Raw Blame History

Workflow Synchronization Guide

How to keep Windsurf workflows consistent across all 7 repos in the workspace.

Quick Reference

Command	Purpose
`zsh scripts/sync-workflows.sh`	Sync common workflows to all repos
`zsh scripts/sync-workflows.sh --dry-run`	Preview changes without applying

Overview

The workspace has 42 workflows across 8 repos. To keep cross-repo workflows (like repo_backup-main-branch, repo_sync-repos) consistent, use the sync script.

Workflow Categories

Category	Prefix	Count	Synced?
Cross-repo	`repo_`	6	✅ Yes
Product release	`release_`	3	❌ No (product-specific)
Testing	`test_`	4	❌ No (product-specific)
Utilities	various	2	Case-by-case

The Sync Script

Location

learning_ai_common_plat/scripts/sync-workflows.sh

What It Syncs

These 6 workflows are pushed from learning_ai_common_plat/.windsurf/workflows/ to all repos:

repo_backup-main-branch.md
repo_backup-and-push.md
repo_sync-repos.md
repo_commit-workspace.md
repo_update-agent-docs.md
refresh-chat-history.md

Target Repos

learning_voice_ai_agent          (LysnrAI)
learning_multimodal_memory_agents (MindLyst)
learning_ai_clock                (ChronoMind)
learning_ai_peakpulse            (PeakPulse)
learning_ai_fastgap              (NomGap)
learning_ai_jarvis_jr            (JarvisJr)

How It Works

Compares source workflow (in common-plat) with destination
Skips if files are identical
Copies if destination is missing or different
Reports how many were updated vs skipped

Output Examples

All up to date:

=== Sync complete ===
  Updated: 0
  Skipped (identical): 36

✓ All workflows are synchronized across all repos.
  No changes needed — everything is up to date.

After editing a workflow:

=== Sync complete ===
  Updated: 6
  Skipped (identical): 30

✓ Synced 6 workflow(s) to repos.
  Run again to verify all repos are identical.

When to Sync

Scenario	Action
Edited a `repo_*` workflow in common-plat	Run sync immediately
New repo added to workspace	Run sync to populate workflows
Workflow behaving differently across repos	Run sync to reconcile
Unsure if workflows are current	Run with `--dry-run` to check

Workflow Naming Convention

Use these prefixes for clarity:

Prefix	Purpose	Example
`repo_`	Cross-repo Git operations	`repo_sync-repos`
`release_`	Product releases	`release_testflight`
`test_`	Testing/verification	`test_coverage`
`product_`	Product-specific ops	`product_build_ios`

Archive Integration

The /refresh-chat-history workflow (which runs daily at 11 PM) also archives all workflows from all repos to:

__LOCAL_LLMs/AI_IDE_CHAT_HISTORY/WINDSURF/repo_workflows/

This provides a historical backup and cross-repo visibility.

Troubleshooting

"Source not found" warning

⚠ Source not found: .../repo_update-agent-docs.md

Fix: The workflow exists in the sync list but not in common-plat. Either:

Create the missing workflow in common-plat, or
Remove it from WORKFLOWS_TO_SYNC in the script

Workflow not syncing

Check that:

Workflow is in WORKFLOWS_TO_SYNC array in the script
Source file exists in learning_ai_common_plat/.windsurf/workflows/
Destination .windsurf/workflows/ directory exists (script auto-creates if missing)

Merge conflicts in workflows

If a workflow was edited independently in two repos:

Decide which version is correct
Copy the correct version to common-plat
Run sync to propagate

Current Workflow Inventory

Repo	Count	Notable Workflows
LysnrAI	14	release-testflight, release-desktop, test-ios-app, test-desktop-app, test-coverage, docker-compose, debug-service, generate-store-assets
PeakPulse	8	mobile-code-quality, production-readiness, repo_push-repos
ChronoMind	6	repo_push-repos
MindLyst	7	mobile-code-quality, release-testflight
NomGap	6	(baseline repo_* workflows)
JarvisJr	6	(baseline repo_* workflows)
Common-plat	7	sync-workflows.sh, refresh-chat-history, all repo_* workflows
Agent-monitoring	1

6.2 KiB Raw Blame History