Context Switch Command Guide¶
Switch between projects without losing architectural context.
Quick Start¶
What It Does¶
Switches the active project context in GuardKit and displays an orientation summary. It points you at the project's architecture docs (docs/architecture/), shows active tasks, and gets you oriented for work - all without changing git branches or filesystem paths.
Important: /context-switch only updates the active-project config. It does NOT:
- Change your git branch
- Move you to a different directory
- Modify any project files
Prerequisites¶
- GuardKit initialized:
guardkit init - Projects registered in
.guardkit/config.yaml - (Optional)
docs/architecture/in the project for architecture context
Usage¶
| Command | Description |
|---|---|
/context-switch |
Show current project context |
/context-switch --list |
List all known projects |
/context-switch <name> |
Switch to named project |
Examples¶
List Known Projects¶
See all projects you can switch between:
Output:
======================================================================
KNOWN PROJECTS
======================================================================
* guardkit (active)
Path: /Users/dev/projects/guardkit
Last accessed: 2026-02-10 14:30
power-of-attorney
Path: /Users/dev/projects/poa-platform
Last accessed: 2026-02-09 16:45
weather-api
Path: /Users/dev/projects/weather-api
Last accessed: 2026-02-08 10:00
======================================================================
Switch context: /context-switch <project-name>
======================================================================
Show Current Context¶
Check which project is active:
Output:
======================================================================
CURRENT PROJECT: guardkit
======================================================================
PATH: /Users/dev/projects/guardkit
ARCHITECTURE:
Methodology: Modular
Components: 8
ADRs: 12 (10 active)
ACTIVE TASKS (3):
- TASK-042: Add user notifications (in_progress)
- TASK-043: Update documentation (in_progress)
- TASK-044: Fix test coverage (backlog)
======================================================================
Commands:
- Overview: /system-overview
- Impact: /impact-analysis TASK-XXX
- Switch: /context-switch <project>
======================================================================
Switch to Another Project¶
Output:
======================================================================
CONTEXT SWITCH: guardkit -> power-of-attorney
======================================================================
PROJECT: power-of-attorney
PATH: /Users/dev/projects/poa-platform
ARCHITECTURE:
Methodology: DDD
Bounded Contexts: 4
ADRs: 7 (5 active, 2 superseded)
KEY COMPONENTS:
- Attorney Management: Donor, attorney CRUD
- Document Generation: LPA forms, templates
- Financial Oversight: Accounts, transactions
- Compliance: OPG registration, verification
ACTIVE TASKS (2):
- TASK-POA-018: Implement Moneyhub integration (in_progress)
- TASK-POA-019: Add audit logging (backlog)
RECENT ACTIVITY:
Last accessed: 2026-02-09 16:45
Last completed: TASK-POA-017 (Feb 9)
======================================================================
ORIENTATION COMPLETE
======================================================================
Ready to work. Suggested next steps:
1. Review active task: /task-status TASK-POA-018
2. Check architecture: /system-overview
3. Analyze impact: /impact-analysis TASK-POA-018
======================================================================
Integration with Other Commands¶
Typical Multi-Project Workflow¶
# 1. See what projects are available
/context-switch --list
# 2. Switch to target project
/context-switch power-of-attorney
# 3. Get full architecture overview
/system-overview
# 4. Check impact of planned work
/impact-analysis TASK-POA-018
# 5. Start working
/task-work TASK-POA-018
With /system-overview¶
After switching, get detailed architecture:
Starting a New Session¶
Refresh context at the start of a work session:
/context-switch # See where you left off
/system-overview # Quick architecture refresh
/task-status # Check task states
What Gets Updated¶
When you run /context-switch:
| Updated | Not Updated |
|---|---|
active_project in config |
Git branch |
last_accessed timestamp |
Current directory, project files, environment variables |
Configuration File¶
Projects are stored in .guardkit/config.yaml:
active_project: guardkit
known_projects:
- name: guardkit
path: /Users/dev/projects/guardkit
last_accessed: 2026-02-10T14:30:00Z
- name: power-of-attorney
path: /Users/dev/projects/poa-platform
last_accessed: 2026-02-09T16:45:00Z
Graceful Degradation¶
No Config File¶
======================================================================
NO PROJECT CONFIGURATION
======================================================================
GuardKit config not found at .guardkit/config.yaml
This project hasn't been initialized with GuardKit yet.
TO INITIALIZE:
guardkit init # Basic initialization
guardkit init fastapi-python # With template
This will create:
- .guardkit/config.yaml
- .claude/ directory
- tasks/ directory structure
======================================================================
Unknown Project¶
======================================================================
PROJECT NOT FOUND: my-new-project
======================================================================
'my-new-project' is not in known projects.
KNOWN PROJECTS:
- guardkit
- power-of-attorney
- weather-api
TO ADD A NEW PROJECT:
1. Navigate to project directory: cd /path/to/my-new-project
2. Initialize GuardKit: guardkit init
3. The project will be added to known_projects automatically
Or add manually to .guardkit/config.yaml
======================================================================
No Architecture Docs¶
When the project has no docs/architecture/, there is no architecture summary to point to:
======================================================================
CONTEXT SWITCH: guardkit -> power-of-attorney
======================================================================
PROJECT: power-of-attorney
PATH: /Users/dev/projects/poa-platform
ARCHITECTURE:
[No docs/architecture/ found - run /system-arch to establish it]
ACTIVE TASKS (2):
- TASK-POA-018: Implement Moneyhub integration (in_progress)
- TASK-POA-019: Add audit logging (backlog)
======================================================================
Note: No architecture context. Run /system-arch, then /system-plan when ready.
======================================================================
Troubleshooting¶
"Project not found" for known project¶
- Check exact spelling: names are case-sensitive
- Verify config file:
cat .guardkit/config.yaml - Re-initialize if needed:
guardkit init
Architecture showing as unavailable¶
- Check the project has a
docs/architecture/directory:ls docs/architecture/ - Establish architecture if missing:
/system-arch "project" - Run system-plan:
/system-plan "project"
Tasks not showing after switch¶
- Ensure
tasks/directory exists at project path - Check task file naming:
TASK-*.md - Verify config
pathpoints to correct directory
Adding a new project manually¶
Edit .guardkit/config.yaml:
known_projects:
# ... existing projects
- name: new-project
path: /Users/dev/projects/new-project
last_accessed: null
See Also¶
- Project architecture lives in
docs/architecture/— establish it with/system-arch - Multi-project registry:
.guardkit/config.yaml - Task orientation after switching:
/task-status