scaffolder | features | documentation | TASKS

scaffolder | features | documentation | TASKS

project:     scaffolder
feature:     documentation
doc-type:    TASKS
status:      accepted
version:     0.1
updated:     2026-03-22
depends-on:  scaffolder | features | documentation | SPEC,
             scaffolder | features | documentation | ARCHITECTURE

---

Pre-work

Before starting any tasks:

1. Read workspace.json at D:\purlshq-dev\ (once it exists) and project.json at the doc site project root
2. Read SPEC.md, ARCHITECTURE.md, and this file from the documentation feature folder
3. Read CLAUDE.md and CURRENT-CODE.md
4. Harley creates all PRs — operator merges. Harley never merges directly.

Version target: v0.12.0 Milestone: v0.12.0 (create on GitHub if not exists)

Critical dependency: The gitignore-operator-files fix shipped via #340 in v0.11.0 and is on all branches. Dependency met.

---

Task 1 — Create workspace directory and config

What: Create the D:\purlshq-dev\ parent directory, the backups\ subdirectory, and the workspace.json config file.

Branch: feature/documentation from dev

Steps:

1. Create directory D:\purlshq-dev\
2. Create directory D:\purlshq-dev\backups\
3. Create D:\purlshq-dev\workspace.json with contents:

   {
     "workspace_root": "D:\\purlshq-dev",
     "engine_root": "D:\\purlshq-dev\\scaffolder-engine",
     "docs_site_root": "D:\\purlshq-dev\\projects-purlshq-com",
     "backups_root": "D:\\purlshq-dev\\backups",
     "github_org": "purlshq",
     "domain": "projects.purlshq.com",
     "projects": ["scaffolder"]
   }

Done when:

• D:\purlshq-dev\ exists
• D:\purlshq-dev\backups\ exists
• D:\purlshq-dev\workspace.json is valid JSON with all keys

Note: No git commit for this task — workspace.json is outside both repos. This is a filesystem operation only.

---

Task 2 — Move engine into workspace

What: Move D:\scaffolder-engine\ to D:\purlshq-dev\scaffolder-engine\.

Steps:

1. Close all terminals, editors, and processes using the engine directory
2. Move: D:\scaffolder-engine\ → D:\purlshq-dev\scaffolder-engine\
3. Verify git remote -v still points to purlshq/scaffolder
4. Verify git status is clean (no unexpected changes from the move)
5. Update shell aliases in ~/.bashrc:
   • harley alias path → /mnt/d/purlshq-dev/scaffolder-engine/...
   • Any other aliases referencing the old path
6. Update ~/.scaffolder-config.json if it contains absolute paths
7. Verify sc create --dry-run "test-project" works from new location
8. Verify harley alias works from new location

Done when:

• Engine is at D:\purlshq-dev\scaffolder-engine\
• D:\scaffolder-engine\ no longer exists
• Git remotes unchanged
• sc and harley commands work from new location

IMPORTANT: The operator must perform the actual directory move. Harley handles alias updates and verification after the move.

---

Task 3 — Initialize Starlight site

What: Create the Starlight project at D:\purlshq-dev\projects-purlshq-com\.

Steps:

1. cd /mnt/d/purlshq-dev/
2. npm create astro@latest -- --template starlight projects-purlshq-com
   • Or manual init if the template command doesn’t match the desired structure
3. Verify astro.config.mjs exists
4. Update astro.config.mjs:

   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';
   
   export default defineConfig({
     integrations: [
       starlight({
         title: 'purlshq projects',
       }),
     ],
   });

5. Verify src/content/docs/ directory exists
6. Remove any default example content from src/content/docs/
7. Create project folder structure:

   src/content/docs/scaffolder/
   src/content/docs/scaffolder/docs/
   src/content/docs/scaffolder/ai-sessions/

8. npm install
9. npm run build — must succeed with empty content folders
10. git init, initial commit

Done when:

• Starlight project exists at D:\purlshq-dev\projects-purlshq-com\
• npm run build succeeds
• Scaffolder folder structure exists under src/content/docs/
• Git initialized with initial commit

---

Task 4 — Create GitHub repo and push

What: Create purlshq/projects-purlshq-com as a private repo on GitHub and push the initialized Starlight site.

Steps:

1. gh repo create purlshq/projects-purlshq-com --private
2. Add remote: git remote add origin https://github.com/purlshq/projects-purlshq-com.git
3. Push: git push -u origin main
4. Verify repo exists on GitHub and is private

Done when:

• purlshq/projects-purlshq-com exists on GitHub, private
• Initial commit is pushed to main

---

Task 5 — Move docs from engine to doc site repo

What: Move scaffolder’s docs/ folder from the engine project directory into the doc site repo.

Steps:

1. Copy entire docs/ directory:

   cp -r /mnt/d/purlshq-dev/scaffolder-engine/projects/scaffolder/docs/* \
     /mnt/d/purlshq-dev/projects-purlshq-com/src/content/docs/scaffolder/docs/

2. Verify all files are present in destination (compare file counts, spot-check content)
3. Remove docs/ from engine project folder:

   rm -rf /mnt/d/purlshq-dev/scaffolder-engine/projects/scaffolder/docs/

4. Commit in doc site repo: docs: move scaffolder docs from engine
5. Commit in engine repo: chore: remove docs (moved to projects-purlshq-com)

Done when:

• All doc files exist at projects-purlshq-com/src/content/docs/scaffolder/docs/
• No docs/ folder exists at scaffolder-engine/projects/scaffolder/
• File count matches, no content lost
• Both repos have clean commits

---

Task 6 — Move ai-sessions from engine to doc site repo

What: Move scaffolder’s ai-sessions/ folder from the engine project directory into the doc site repo.

Steps:

1. Copy entire ai-sessions/ directory:

   cp -r /mnt/d/purlshq-dev/scaffolder-engine/projects/scaffolder/ai-sessions/* \
     /mnt/d/purlshq-dev/projects-purlshq-com/src/content/docs/scaffolder/ai-sessions/

2. Verify all files are present (CURRENT-CHAT.md, CURRENT-CODE.md, logs/)
3. Remove ai-sessions/ from engine project folder:

   rm -rf /mnt/d/purlshq-dev/scaffolder-engine/projects/scaffolder/ai-sessions/

4. Commit in doc site repo: docs: move scaffolder ai-sessions from engine
5. Commit in engine repo: chore: remove ai-sessions (moved to projects-purlshq-com)

Done when:

• All session files exist at projects-purlshq-com/src/content/docs/scaffolder/ai-sessions/
• No ai-sessions/ folder exists at scaffolder-engine/projects/scaffolder/
• CURRENT-CHAT.md, CURRENT-CODE.md, and logs/ all intact
• Both repos have clean commits

---

Task 7 — Add Starlight frontmatter to all markdown files

What: Add YAML frontmatter with title field to every markdown file in the doc site repo.

Steps:

1. Find all .md files under src/content/docs/scaffolder/
2. For each file, add YAML frontmatter at the very top:

   ---
   title: "[pipe-separated name matching the # heading]"
   ---

3. The title value comes from the first # heading in each file
4. Do NOT modify any existing content — only prepend frontmatter
5. Verify npm run build succeeds after adding frontmatter
6. Commit: docs: add Starlight frontmatter to all markdown files

Done when:

• Every .md file has YAML frontmatter with title
• No existing content is modified
• npm run build succeeds
• Sidebar shows all docs with correct titles

---

Task 8 — Create project config

What: Create project.json for scaffolder in the doc site repo.

Steps:

1. Create src/content/docs/scaffolder/project.json:

   {
     "project": "scaffolder",
     "github_repo": "purlshq/scaffolder",
     "scale_tier": "project-management",
     "engine_project_path": "projects\\scaffolder",
     "linear_project": null,
     "version": "0.11.0"
   }

2. Verify Starlight ignores it (non-markdown files don’t appear in sidebar)
3. Verify npm run build still succeeds
4. Commit: config: add scaffolder project.json

Done when:

• project.json exists with correct values
• Build still succeeds
• File does not appear in site navigation

---

Task 9 — Rewrite reference files to use config keys

What: Remove all hardcoded paths from CHAT-REFERENCE.md, PROJECT-INSTRUCTIONS.md, CLAUDE.md, and any other reference files. Replace with config key references.

Steps:

1. Read current versions of:
   • _system/CHAT-REFERENCE.md
   • Engine root PROJECT-INSTRUCTIONS.md
   • Engine project CLAUDE.md
   • Engine project STANDARDS.md
2. Rewrite every literal path to use config key notation:
   • D:\scaffolder-engine\... → {engine_root}/...
   • D:\purlshq-dev\projects-purlshq-com\... → {docs_site_root}/...
   • Session file paths → {docs_site_root}/src/content/docs/{project}/ai-sessions/...
   • Doc paths → {docs_site_root}/src/content/docs/{project}/docs/...
3. Add a “Config resolution” section to CHAT-REFERENCE.md explaining where workspace.json and project.json live and how to read them
4. Update session start instructions in PROJECT-INSTRUCTIONS.md to read workspace.json first, then project.json, then session files
5. Update Harley’s CLAUDE.md to read docs and session files from config-resolved paths
6. Update Harley’s session-end hooks if they contain absolute paths
7. Commit in doc site repo (for CHAT-REFERENCE.md if it moves there): config: rewrite reference files to use config keys
8. Commit in engine repo (for CLAUDE.md, PROJECT-INSTRUCTIONS.md, etc.): config: rewrite reference files to use config keys

Done when:

• No literal paths remain in any reference file
• All paths use {config_key} notation
• CHAT-REFERENCE.md documents the config resolution pattern
• Joker can follow session start instructions using config
• Harley can follow session start instructions using config

---

Task 10 — Connect Cloudflare Pages

What: Connect the GitHub repo to Cloudflare Pages and configure the custom domain.

IMPORTANT: This task requires operator action in the Cloudflare dashboard. Harley cannot access Cloudflare directly.

Operator steps:

1. Log in to Cloudflare dashboard
2. Go to Workers & Pages → Create → Pages → Connect to Git
3. Select purlshq/projects-purlshq-com repository
4. Configure build settings:
   • Production branch: main
   • Framework preset: Astro
   • Build command: npm run build
   • Build output directory: dist
5. Deploy
6. Go to Custom domains → Add custom domain
7. Enter projects.purlshq.com
8. Cloudflare auto-configures DNS (since domain is on Cloudflare)
9. Wait for SSL certificate provisioning
10. Verify site loads at projects.purlshq.com

Done when:

• Cloudflare Pages project exists and is connected to the repo
• Push to main triggers build
• Site accessible at projects.purlshq.com
• SSL certificate active

---

Task 11 — Set up Cloudflare Access

What: Lock projects.purlshq.com to operator email only.

IMPORTANT: This task requires operator action in the Cloudflare dashboard. Harley cannot access Cloudflare directly.

Operator steps:

1. In Cloudflare dashboard → Zero Trust → Access → Applications
2. Add an application → Self-hosted
3. Application domain: projects.purlshq.com
4. Application name: “purlshq projects”
5. Add policy:
   • Policy name: “Operator only”
   • Action: Allow
   • Include: Emails — [operator email address]
6. Authentication method: One-time PIN
7. Save
8. Test: visit projects.purlshq.com in incognito → should see Cloudflare Access login → enter email → receive OTP → access site

Done when:

• Cloudflare Access policy is active on projects.purlshq.com
• Unauthenticated visitors are blocked
• Operator can authenticate via email OTP
• Site content is visible after authentication

---

Task 12 — Final verification

What: End-to-end verification that everything works.

Steps:

1. Verify workspace.json is readable and correct
2. Verify project.json is readable and correct
3. npm run build in doc site repo — clean build
4. Push a test change to a doc file → verify auto-deploy
5. Browse projects.purlshq.com:
   • Sidebar shows scaffolder project
   • Docs are navigable
   • ai-sessions are navigable
   • Breadcrumbs work
   • Right-side “on this page” nav works
   • Search returns results
   • Light/dark toggle works
6. Verify Joker session flow:
   • Joker reads workspace.json → resolves paths
   • Joker reads CURRENT-CHAT.md from doc site repo
   • Joker can write to doc site repo
7. Verify Harley session flow:
   • Harley reads workspace.json → resolves paths
   • Harley reads CURRENT-CODE.md from doc site repo
   • Harley reads TASKS.md, SPEC.md from doc site repo
   • Harley works in engine project folder for code
8. Verify engine still works:
   • sc create --dry-run "test-project" from new location
   • harley alias works
   • Git remotes unchanged
9. Verify no hardcoded paths remain in reference files

Done when:

• All SPEC acceptance criteria pass
• Site is live at projects.purlshq.com
• Both Joker and Harley workflows function correctly
• No literal paths in any reference file

---

Task summary

#	Task	Who	Depends on
1	Create workspace dir + config	Harley	PR #324 merged
2	Move engine into workspace	Operator + Harley	Task 1
3	Initialize Starlight site	Harley	Task 2
4	Create GitHub repo + push	Harley	Task 3
5	Move docs to doc site repo	Harley	Task 4
6	Move ai-sessions to doc site repo	Harley	Task 5
7	Add Starlight frontmatter	Harley	Task 6
8	Create project config	Harley	Task 7
9	Rewrite reference files	Harley	Task 8
10	Connect Cloudflare Pages	Operator	Task 4
11	Set up Cloudflare Access	Operator	Task 10
12	Final verification	Harley + Operator	All above

Tasks 10-11 can run in parallel with Tasks 5-9 since they only depend on the GitHub repo existing (Task 4).

---

TASKS — draft. Awaiting operator review and acceptance.