atman-33 project-manage
Registers external projects in the project registry and manages the lifecycle of existing registry entries. Projects can have instruction files such as AGENTS.md, CLAUDE.md, and GEMINI.md at their root; these are detected during registration and persisted in projects/<id>/project.yaml.
Execution and context assignment no longer use a global active-project list. After registration, choose Execution Project and Context Projects from the relevant Noctis mission or OpenCode session surface.
Commands
1. Register a New Project
Detects instruction files at the project root and stores metadata in projects/<id>/project.yaml.
scripts/project_register.sh \
--id <project_id> \
--name "<name>" \
--root "<absolute_path>" \
[--serena-project "<value>"] \
[--force]
| Parameter | Required | Description |
|---|---|---|
--id |
Yes | Unique project identifier (e.g., my-app) |
--name |
Yes | Human-readable project name |
--root |
Yes | Absolute path to project root |
--serena-project |
No | Value confirmed by activate_project (project name or path). When provided, stored as serena_project in the YAML. When omitted, the field is not written. |
--force |
No | Overwrite existing registration without prompting |
Example:
# After confirming activation value (see Typical Workflow below)
scripts/project_register.sh \
--id "my-app" \
--name "My App" \
--root "/home/atman/repos/my-app" \
--serena-project "my-app" # value confirmed by activate_project
Output: projects/my-app/project.yaml with detected instruction files and serena_project.
2. Refresh Registered Metadata
Refresh a project's detected metadata after adding or changing instruction files.
scripts/project_register.sh \
--id "client-x" \
--name "Client X" \
--root "/home/atman/repos/client-x" \
--force
If serena_project is already present in the existing YAML, re-registering without --serena-project preserves that value.
After registration, inspect the result in the Projects screen or by reading projects/<id>/project.yaml.
3. Rename or Re-Key a Registered Project
Updates the registry name, the registry ID, or both while preserving the existing working tree root and any stored serena_project value.
scripts/project_rename.sh \
--id "client-x" \
[--new-id "client-z"] \
[--name "Client Z"] \
[--force]
| Parameter | Required | Description |
|---|---|---|
--id |
Yes | Current registered project identifier |
--new-id |
No | New project identifier when re-keying the registry entry |
--name |
No | New human-readable project name |
--force |
No | Skip overwrite prompts during re-registration |
At least one of --new-id or --name must be provided.
Examples:
# Rename only the display name
scripts/project_rename.sh \
--id "client-x" \
--name "Client X Platform"
# Change both the registry ID and display name
scripts/project_rename.sh \
--id "client-x" \
--new-id "client-platform" \
--name "Client Platform" \
--force
After the rename, refresh the Projects page manually to see the updated registry entry.
4. Delete a Registered Project
Removes a project from the FF15 registry only. It does not delete the underlying working tree.
scripts/project_delete.sh \
--id "client-x" \
[--force]
| Parameter | Required | Description |
|---|---|---|
--id |
Yes | Registered project identifier to remove |
--force |
No | Skip the confirmation prompt |
Example:
scripts/project_delete.sh --id "client-x" --force
After deletion, refresh the Projects page manually to remove the entry from the list.
Typical Workflow
# 1. Try activate_project to confirm the working value.
# In WSL: UNC path → Linux path.
# Outside WSL: project ID → absolute path.
# Use whichever succeeds first as the --serena-project value.
# 2. Register the project with the confirmed value
scripts/project_register.sh \
--id "client-x" \
--name "Client X" \
--root "/home/atman/repos/client-x" \
--serena-project "<confirmed_value>" # value confirmed in step 1
# 3. Verify the registry entry
cat projects/client-x/project.yaml
# 4. Use the registered project from the UI
# - Projects page: browse metadata, Open Folder, VS Code
# - Noctis mission / OpenCode session: pick Execution Project / Context Projects
Registered instruction files are later resolved through mission-local or session-local execution-context state. There is no standalone activation step.
Serena Activation
Before registering, confirm which value works for activate_project.
In WSL environments, try in order and stop at first success:
- UNC path (e.g.,
\\wsl$\Ubuntu\home\atman\repos\client-x) root_pathas-is (Linux path, e.g.,/home/atman/repos/client-x)
Outside WSL, try in order and stop at first success:
- Project ID alone (e.g.,
client-x) — fastest if already registered in Serena - Absolute project path
Pass the successful value as --serena-project when running project_register.sh. This ensures serena_project is set correctly in the YAML from the start.
If registration was done without --serena-project: re-register with --force after confirming the activation value.
What Gets Stored
projects/<id>/project.yaml:
id: 'client-x'
name: 'Client X'
root_path: '/home/atman/repos/client-x'
serena_project: '\\wsl$\Ubuntu\home\atman\repos\client-x' # optional; use the confirmed Serena activation value
instruction_files:
- path: '/home/atman/repos/client-x/AGENTS.md'
enabled: true
Re-registering After Changes
If a project's instruction files are added or modified:
scripts/project_register.sh \
--id "client-x" \
--name "Client X" \
--root "/home/atman/repos/client-x" \
--force
Detected instruction files will be refreshed with enabled: true. No need to re-activate.
If serena_project is already present in the existing YAML, re-registering without --serena-project preserves that value.
Note: project_register.sh now writes YAML-safe single-quoted scalars for path-like fields. This avoids parse failures when serena_project contains backslashes, such as UNC paths in WSL.
project_rename.sh reuses project_register.sh internally so the same instruction-file refresh and YAML-safe quoting behavior apply during rename operations.
Registry vs Runtime Selection
- Registration stores long-lived project metadata in
projects/<id>/project.yaml. - Runtime assignment happens per mission or session through
Execution ProjectandContext Projects. - The FF15 web app no longer provides a global active-project config file or activation CLI.
Error Handling
| Error | Cause | Solution |
|---|---|---|
| Symlink detected | Project root contains symlinks | Use a real path |
| Project not found in projects/ | Requested ID is not registered | Run project_register.sh first |
| Rename target already exists | --new-id already has a registry entry |
Re-run with the correct target or pass --force after confirming overwrite |
| Cannot resolve path | Non-existent root path | Verify the path exists |
| Failed to write YAML | Lock timeout | Retry; check for stale .lock files |
When to Use This Skill
- Starting work on a new external project
- Onboarding multiple projects for parallel work
- Re-registering after instruction files were added or changed
- Renaming a registry entry or correcting its display name
- Deleting a registry entry without touching the working tree
- Explaining how registered projects appear in Projects / mission / session UI
Don't use when:
- Selecting runtime execution or context for a mission/session — do that from the relevant UI surface
- The project has no instruction files — registration still works (with a warning)