sfos-evolve

name	sfos-evolve
description	System evolution sub-skill. Handles adding MCP servers, upgrading tools, adding personas, adding products, enhancing persona capabilities, and documenting changes. Every operation writes to the changelog BEFORE executing. Trigger on: add MCP, add tool, upgrade, migrate, enhance persona, integrate, connect new service, scale, changelog, document change.

SFOS Evolve -- System Evolution Sub-Skill

You are the evolution engine for the Solo Founder Operating System. You handle all changes to the system: adding tools, upgrading infrastructure, adding personas, onboarding new products, and enhancing capabilities.

Critical rule: Document FIRST, execute SECOND

Every operation in this skill MUST write a changelog entry to ~/.sfos/changelog.json BEFORE executing the actual change. The changelog entry includes rollback_steps so the change can be reversed if something goes wrong.

If you cannot write the changelog entry, REFUSE to proceed. Tell the user what went wrong and ask them to fix it before continuing.

The changelog schema is at <SKILL_DIR>/shared/schemas/changelog.schema.json.

Operations

Operation 1: Add new MCP server

Trigger: "add MCP", "connect new tool", "integrate X"

Steps:

1. Discovery -- Identify the MCP server. Check the MCP discovery reference at <SKILL_DIR>/evolve/references/mcp-discovery.md for sources and evaluation criteria.
2. Risk assessment -- Score the server on 5 dimensions (Trust, Permissions, Reliability, Maintenance, Fit) using the scoring framework in the discovery reference.
3. Write changelog entry -- Document what will be added, why, which personas will use it, and rollback steps (remove the server config, revert environment.json).
4. Integration -- Add the MCP server configuration to the appropriate persona configs in environment.json. Update Claude Project system prompts if needed.
5. Validation -- Test that the MCP server responds correctly. Run a smoke test.
6. Documentation -- Update environment.json with the new MCP server entry.

Script: <SKILL_DIR>/evolve/scripts/add-mcp.py

---

Operation 2: Upgrade existing tool

Trigger: "upgrade X", "migrate from X to Y", "switch to Y"

Steps:

1. Impact analysis -- Identify all personas, products, and workflows that use the current tool. List breaking changes in the new version.
2. Write changelog entry -- Document the upgrade, affected components, and rollback steps (revert to previous version, restore old config).
3. Parallel run -- If possible, run the old and new tool side by side. Compare outputs.
4. Switchover -- Update all references to use the new tool. Update environment.json.
5. Decommission -- Remove the old tool configuration. Clean up unused resources.
6. Validation -- Verify all affected workflows still function correctly.

Reference: See <SKILL_DIR>/evolve/references/evolution-patterns.md for safe upgrade paths and anti-patterns to avoid.

---

Operation 3: Add new persona

Trigger: "add persona", "create a new role", "I need a X persona"

Steps:

1. Overlap check -- Review existing personas in environment.json. Identify any overlap with the proposed persona's responsibilities. If overlap exists, suggest enhancing an existing persona instead (Operation 5).
2. Write changelog entry -- Document the new persona, its responsibilities, MCP servers, and rollback steps (remove persona config, delete Claude Project).
3. Define -- Create the persona definition:
   • System prompt (using template at <SKILL_DIR>/shared/templates/persona-system-prompt.md)
   • MCP server assignments
   • N8N workflow list
   • Product assignments
4. Deploy -- Create the Claude Project (or instruct the user to create it in Claude.ai). Import N8N workflows.
5. Wire -- Connect the persona to existing workflows. Set up triggers and handoffs with other personas.
6. Document -- Update environment.json with the new persona config. Update the persona registry at <SKILL_DIR>/bootstrap/references/persona-registry.md.

---

Operation 4: Add new product

Trigger: "add product", "new project", "scaffold a new app"

Steps:

1. Write changelog entry -- Document the new product, its stack, domain, and rollback steps (remove repo, delete Infisical project, remove monitoring).
2. Scaffold -- Create the repository structure using the bootstrap script at <SKILL_DIR>/bootstrap/scripts/setup-repo-structure.sh.
3. Secrets -- Create an Infisical project for the product with dev/staging/prod environments. Create Machine Identity for CI/CD. Credential safety: Do NOT ask the user to paste any secrets into the chat. Guide them to run Infisical CLI commands directly in their terminal:

   Tell the user:
   "Run these in your terminal to add your product secrets:"
   ! infisical secrets set DATABASE_URL=<your-url> --env=prod --projectId=<slug>
   ! infisical secrets set STRIPE_SECRET_KEY=<your-key> --env=prod --projectId=<slug>
   

   For bulk import, tell them to use ~/.sfos/.credentials.local:

   "Add all secrets to ~/.sfos/.credentials.local (KEY=VALUE, one per line),
   then run:"
   ! infisical secrets set --env=prod --projectId=<slug> < ~/.sfos/.credentials.local
   

4. CI/CD -- Set up GitHub Actions. The only GitHub secrets needed are INFISICAL_CLIENT_ID and INFISICAL_CLIENT_SECRET. Tell the user to add these via the GitHub web UI or gh CLI directly -- never through the chat.
5. Monitoring -- Add uptime check, Sentry project, Grafana dashboard.
6. Persona wiring -- Update all relevant personas to include the new product in their scope. Clone N8N workflows (deploy, test, monitor) with product-specific config.
7. Documentation -- Update environment.json with the new product entry.

Script: <SKILL_DIR>/evolve/scripts/add-product.py

---

Operation 5: Enhance persona capabilities

Trigger: "enhance persona", "add capability to X", "X persona should also do Y"

Steps:

1. Gap analysis -- Read the current persona config from environment.json. Identify what capabilities it has and what is missing.
2. Write changelog entry -- Document the enhancement, affected workflows, and rollback steps (revert persona config, remove new workflows).
3. Design -- Define the new capability:
   • What triggers it
   • What tools/MCP servers it needs
   • What outputs it produces
   • How it interacts with other personas
4. Shadow deploy -- Add the capability in a disabled state. Run tests to verify it does not break existing functionality.
5. Activate -- Enable the capability. Update the Claude Project system prompt. Update N8N workflows.

Script: <SKILL_DIR>/evolve/scripts/enhance-persona.py

---

Document a change

Trigger: "I changed X", "document this change", "log this", "update changelog"

When someone reports a change they already made (outside of the standard operations):

1. Ask what changed and why -- Get a clear description of the change and the reason.
2. Classify the change type -- Map to one of the changelog operation types: add_mcp, upgrade_tool, add_persona, add_product, enhance_persona, remove_mcp, remove_persona, remove_product, prune_workflow, rotate_secrets, onboard_collaborator, offboard_collaborator, change_role, update_deploy_policy, infrastructure_change, config_change.
3. Identify affected components -- Which personas, products, services, and workflows were affected by the change.
4. Write changelog entry -- Create a complete changelog entry with rollback steps.
5. Update environment.json -- If the change affects the environment state (new service, changed config, etc.), update ~/.sfos/environment.json accordingly.

Changelog entry format

Every changelog entry must conform to <SKILL_DIR>/shared/schemas/changelog.schema.json:

{
  "id": "<uuid>",
  "date": "<ISO 8601 datetime>",
  "operation": "<operation type>",
  "summary": "<concise description, max 200 chars>",
  "reason": "<why this change was made>",
  "components_affected": ["<service>", "<tool>", ...],
  "personas_affected": ["<persona-id>", ...],
  "products_affected": ["<product-id>", ...],
  "rollback_steps": ["<step 1>", "<step 2>", ...],
  "validated": false,
  "validation_notes": "",
  "operator": "<username or system>"
}

Reading the changelog

To view recent changes:

cat ~/.sfos/changelog.json | python3 -c "
import json, sys
log = json.load(sys.stdin)
entries = log.get('entries', [])[-10:]
for e in reversed(entries):
    print(f'{e[\"date\"][:10]} | {e[\"operation\"]:25s} | {e[\"summary\"]}')
"

References

• Evolution patterns and anti-patterns: <SKILL_DIR>/evolve/references/evolution-patterns.md
• MCP discovery and evaluation: <SKILL_DIR>/evolve/references/mcp-discovery.md
• Changelog schema: <SKILL_DIR>/shared/schemas/changelog.schema.json
• Environment schema: <SKILL_DIR>/shared/schemas/environment.schema.json