fix(setup): make gstack skills discoverable and usable in Factory Droid

[morluto]

Problem

Factory Droid support is currently broken for gstack installs via:

cd ~/gstack && ./setup --host factory

The generated skills exist on disk, but Droid cannot reliably discover or load them. In practice this means gstack skills may not appear in the / menu, and the install layout is not compatible with Droid's expected discovery and registry model.

Reproduction

1. Install gstack for Factory Droid:

   cd ~/gstack && ./setup --host factory

2. Restart Droid
3. Type / — no gstack skills appear (debug, fix, test, qa, etc. are missing)
4. Check the installed entries:

   ls ~/gstack/.factory/skills/    # generated skill directories exist in the repo
   ls -l ~/.factory/skills/        # gstack entries exist, but as absolute symlinks into ~/gstack
   ls ~/.agents/skills/            # empty — skills not copied here

Root Cause: Three Bugs in link_factory_skill_dirs()

Bug 1: Wrong target for installed skill contents

The original install did create entries in ~/.factory/skills/, but they pointed to the wrong place for discovery. gstack generated Factory skills in ~/gstack/.factory/skills/ and then linked ~/.factory/skills/ entries back into that project directory, while Droid expects the canonical skill contents to live under ~/.agents/skills/.

Bug 2: Absolute symlinks

gstack created absolute symlinks in ~/.factory/skills/:

ln -snf /Users/will/gstack/.factory/skills/gstack-qa ~/.factory/skills/gstack-qa

Droid follows only relative symlinks (../../.agents/skills/{skill}). Absolute paths are ignored.

Bug 3: Wrong sourceType in lockfile

gstack registered entries with sourceType: "local":

{
  "sourceType": "local",
  "sourceUrl": "file:///Users/will/gstack/.factory/skills/gstack-qa"
}

Droid's lockfile reader ignores sourceType: "local" entirely. Zero of the 57 working skills use this value — all use sourceType: "github".

How Droid Discovers Skills (Two-Tier System)

Droid startup
    │
    ├── Tier 1: Scans ~/.factory/skills/
    │       ├── Follows relative symlinks ──→ ~/.agents/skills/gstack-factory*/SKILL.md
    │       └── Ignores: absolute symlinks and project-local targets
    │
    └── Tier 2: Reads ~/.agents/.skill-lock.json (if present)
            ├── sourceType: "github"  ──→ loads skill ✓
            └── sourceType: "local"  ──→ ignores skill ✗

A skill appears in / when both conditions are met:

1. Relative symlink exists in ~/.factory/skills/ pointing to the isolated Factory copy in ~/.agents/skills/gstack-factory*
2. Lockfile entry keeps the public skill name (for example gstack-qa) with sourceType: "github" in ~/.agents/.skill-lock.json

The Fix (4 commits)

Commit 1: Use relative symlinks in ~/.factory/skills/

Changed from absolute paths to the pattern all working skills use:

ln -snf "../../.agents/skills/$skill_name" "$target"

This commit also removes the old skip for the root gstack skill, so that directory can now be linked like the rest of the skill set.

Commit 2: Copy skills to ~/.agents/skills/

Droid reads skill files from ~/.agents/skills/. Symlinks pointing into ~/gstack/.factory/skills/ do not work — must be real directories.

cp -r "$skill_dir" "$HOME/.agents/skills/$skill_name"

This means Factory now reads a copied snapshot from ~/.agents/skills/, not directly from the repo checkout. If you edit a skill in ~/gstack, rerun ./setup --host factory to refresh Droid's copy.

Commit 3: Register with sourceType: "github"

Updated the Python lockfile registration script to use the only sourceType Droid actually loads:

{
  "source": "gstack/gstack-qa",
  "sourceType": "github",
  "sourceUrl": "file:///Users/will/.agents/skills/gstack-qa"
}

Commit 4: Isolate Factory copies and bootstrap the lockfile

The first three fixes made Droid discovery work, but they still wrote Factory-generated skill files into the shared ~/.agents/skills/gstack-* namespace. That risked clobbering non-Factory installs that also use ~/.agents/skills/.

The final fix isolates Factory-owned copies under gstack-factory* names while keeping the public Droid-facing names unchanged:

cp -r "$skill_dir" "$HOME/.agents/skills/gstack-factory-qa"
ln -snf "../../.agents/skills/gstack-factory-qa" ~/.factory/skills/gstack-qa

It also bootstraps ~/.agents/.skill-lock.json on first install instead of skipping registration on clean machines:

{
  "version": 3,
  "dismissed": {},
  "lastSelectedAgents": [],
  "skills": {}
}

The lockfile still registers the public skill name (gstack-qa) so Droid shows the expected /qa command, but the sourceUrl now points at the isolated Factory copy:

{
  "source": "gstack/gstack-qa",
  "sourceType": "github",
  "sourceUrl": "file:///Users/will/.agents/skills/gstack-factory-qa"
}

Validation

After applying the fix:

# 1. Install
cd ~/gstack && ./setup --host factory

# 2. Verify filesystem layout
ls -l ~/.factory/skills/gstack-qa
# should show: ../../.agents/skills/gstack-factory-qa

test -d ~/.agents/skills/gstack-factory-qa && echo "copied"
# should print: copied

# 3. Verify lockfile
python3 -c "
import json
with open('$HOME/.agents/.skill-lock.json') as f:
    lock = json.load(f)
entry = lock['skills']['gstack-qa']
print(entry['sourceType'], entry['sourceUrl'])"
# should print: github file:///.../gstack-factory-qa

# 4. Restart Droid
# Type /qa in Droid — skill now appears ✓

Closes #661.

[morluto]

@garrytan