@firatcand/forge 0.1.0

package/skills/push-to-linear/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: push-to-linear
+description: Push phases.yaml to Linear — creates project, cycles per phase, issues with depends_on relations. Lightweight; uses user's Linear MCP.
+tools: Read, Edit
+subagent: linear-syncer
+---
+
+# /push-to-linear
+
+Delegate to the `linear-syncer` subagent.
+
+## Preconditions
+
+- `plans/phases.yaml` exists
+- Linear MCP configured globally OR user has Linear API key
+
+## If Linear MCP available
+
+linear-syncer subagent uses MCP directly:
+1. Create Linear project (or find existing if `linear_project_id` set)
+2. For each phase: create a Linear Cycle
+3. For each task: create issue with priority, estimate, parent (if any), and "blocked by" relations
+4. Link Linear project to GitHub repo (enables native sync)
+5. Update phases.yaml with `linear_project_id`, `linear_team_id`, and `linear_id` per task
+
+## If no Linear MCP
+
+Print phases.yaml in Linear-import-friendly format. Tell user:
+- Open Linear → Import
+- Paste the structured tasks
+- Link the project to the GitHub repo manually in Linear settings
+
+## Linear ↔ GitHub sync
+
+Once linked:
+- Branch `feat/{LINEAR-ID}-slug` auto-links to issue
+- PR opened with `[LINEAR-ID]` in title → issue moves to "In Review"
+- PR merged → issue moves to "Done"
+
+## Output
+
+Linear project URL. Confirmation that GH sync is active. Updated phases.yaml committed.

package/skills/qa/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: qa
+description: Run test suite, browser checks, and verify acceptance criteria. Bootstrap test framework if missing.
+tools: Bash(*), Read, Edit
+subagent: qa-engineer
+---
+
+# /qa
+
+Delegate to `qa-engineer` subagent.
+
+## Process
+
+1. Detect test framework — if absent, offer to bootstrap (Vitest + Playwright defaults)
+2. Run unit + integration tests
+3. For UI tasks: run Playwright on key flows from PRD
+4. Verify acceptance criteria from Linear issue are met
+5. Report failures; auto-suggest fixes for trivial ones
+
+## Test-or-die enforcement
+
+If task is a bug fix and there's no regression test, REFUSE to pass /qa. Generate the regression test first.

package/skills/retro/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: retro
+description: Write a phase retrospective. Auto-invoked by /phase-gate but can run standalone.
+tools: Read, Write, Bash(git*)
+---
+
+# /retro
+
+## Args
+
+- `phase-{N}` (e.g., `phase-1`)
+
+## Process
+
+1. Gather data from Linear (closed tasks in cycle N) + git log (commits during cycle) + learnings written during cycle
+2. Synthesize:
+   - What shipped (count + highlights)
+   - Cycle time avg
+   - Decisions made (with PR links)
+   - Scope changes from original phases.yaml
+   - Learnings (count + key ones)
+   - What to do differently next phase
+3. Write to `docs/retros/phase-{N}.md` using `templates/retro.template.md`
+
+## Output
+
+Retro file path + 5-bullet summary printed to terminal.

package/skills/review/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: review
+description: Run code-reviewer, security-auditor (if CRITICAL.md path touched), and design-reviewer (if UI task) on current diff.
+tools: Read, Bash(git*)
+---
+
+# /review
+
+## Process
+
+1. Run `git diff dev...HEAD` to get current diff
+2. Always invoke `code-reviewer` subagent
+3. If diff touches paths in CRITICAL.md, invoke `security-auditor`
+4. If task type is "design" or "frontend", invoke `design-reviewer`
+5. Aggregate findings; categorize by severity (block / improvement / nit)
+6. Print summary; ask user to address blocks before /ship
+
+## Output
+
+Markdown summary of findings per reviewer, with file:line references.

package/skills/setup-repo/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: setup-repo
+description: Bootstrap the GitHub repo for a forge project — repo creation, branch protection, GitHub Environments, CI workflows, secrets configuration.
+tools: Read, Write, Edit, Bash(gh*), Bash(git*)
+subagent: devops-engineer
+---
+
+# /setup-repo
+
+Delegate to the `devops-engineer` subagent.
+
+## Preconditions
+
+- `gh` CLI installed and authenticated
+- spec/PRD.md exists
+- Run from inside the project directory
+
+## Steps (transparent — show each to user, don't hide)
+
+1. **Verify gh CLI**: `gh auth status`
+2. **Create repo**: `gh repo create [name] --private --source=. --remote=origin`
+   - Or skip if origin already exists
+3. **Initial commit**: if no commits, commit current state to `main`
+4. **Branch dev from main**: `git checkout -b dev && git push origin dev`
+5. **Branch protection on main**:
+   - Require PR review (1)
+   - Require `test` status check
+   - No direct pushes
+   - No force pushes
+6. **Branch protection on dev**:
+   - Require PR review (1)
+   - Require `test` status check
+7. **GitHub Environments**:
+   - `development` (auto-deploy, no approval)
+   - `production` (manual approval)
+8. **Copy CI workflows** from `templates/github-workflows/` to `.github/workflows/`:
+   - `claude-issue.yml`
+   - `claude-pr-review.yml`
+   - `test.yml`
+   - `claude-scheduled.yml`
+9. **Generate `.env.example`** from SPEC.md env_vars list
+10. **Setup Claude Code OAuth token**:
+    - Prompt user: `claude setup-token`
+    - Read token from clipboard or stdin
+    - Set as repo secret: `gh secret set CLAUDE_CODE_OAUTH_TOKEN`
+11. **Commit and push**: `.github/`, updated `.env.example`
+
+## Each step shown to user
+
+Don't run all 11 steps silently. Print each:
+
+```
+[1/11] Verifying gh CLI authentication... ✓
+[2/11] Creating repo firatcand/time-logger... ✓
+[3/11] Initial commit on main... ✓
+...
+```
+
+User can interrupt at any step.
+
+## Output
+
+Repo URL + summary of what was configured. Branch protection rules summary. Workflow files list.

package/skills/ship/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: ship
+description: Push branch, run final gates (tests, secrets scan, conventional commit), open PR with Linear issue ID, mark issue In Review.
+tools: Bash(*), Read
+---
+
+# /ship
+
+## Gates (all must pass)
+
+1. **Tests**: `npm test` (or detected equivalent) passes
+2. **Type check**: `npm run typecheck` (if applicable) passes
+3. **Lint**: `npm run lint` (if applicable) passes
+4. **Secrets scan**: `gitleaks detect` on the diff
+5. **Conventional commit**: at least one commit on this branch follows `feat|fix|chore|docs(scope): message`
+6. **Test-or-die**: new code has new tests; bug fixes have regression tests
+7. **Multi-model review**: if diff touches CRITICAL.md paths, `/codex review` was run
+
+If any gate fails, list what's missing. Do not proceed.
+
+## Push and PR
+
+1. `git push origin HEAD`
+2. `gh pr create --base dev --title "[LINEAR-ID] {title from issue}" --body "{description}"`
+3. PR body template:
+   - What changed (3-5 bullets)
+   - Why
+   - How to test
+   - Linked: closes #LINEAR-ID
+4. Linear native sync: issue auto-moves to "In Review"
+
+## Output
+
+PR URL. Linear issue link. Reminder to run `/learn` if anything notable happened.

package/skills/sync-status/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: sync-status
+description: Pull current Linear state and reconcile with local phases.yaml. Useful when issues were closed/reopened in Linear directly.
+tools: Read, Edit
+subagent: linear-syncer
+---
+
+# /sync-status
+
+Read `plans/phases.yaml`. For each task with a `linear_id`, query Linear for current status. Update `phases.yaml` task status fields if drifted.
+
+Report any divergence to user (e.g., "TLOG-103 closed in Linear but local says Todo").
+
+This isn't usually needed — Linear ↔ GitHub native sync handles most cases. Use when manual closes happen in Linear.

package/templates/BRIEF.template.md

@@ -0,0 +1,34 @@
+# {{PROJECT_NAME}} — Brief
+
+> Forged: {{ISO_DATE}}
+> Status: draft (Gate 1 pending)
+
+## The pain
+<!-- REQUIRED: Synthesized from forge Q1. Concrete, not abstract. -->
+
+## The user
+<!-- REQUIRED: Specific persona. JTBD format: When ___, I want ___, so I ___. -->
+
+## The unfair advantage
+<!-- REQUIRED: From Q2. Honest list of what's defensible vs aspirational. -->
+
+## The smallest valuable thing
+<!-- REQUIRED: From Q3. 3-5 sentence v1 description. -->
+
+## Non-goals
+<!-- REQUIRED: From Q4. The trap list. At least 3 bullets. -->
+- 
+- 
+- 
+
+## North-star metric
+<!-- REQUIRED: From Q5. Single number with target value and timeframe. -->
+
+## Kill criteria
+<!-- REQUIRED: From Q6. Structured by horizon. -->
+- At week 4: 
+- At week 12: 
+- At month 6: 
+
+## Open questions
+<!-- Anything Q&A didn't fully resolve. Carry forward to /draft-prd. -->

package/templates/CLAUDE.project.template.md

@@ -0,0 +1,37 @@
+# {{PROJECT_NAME}}
+
+## Stack
+<!-- Auto-populated by /draft-spec — keep in sync with spec/SPEC.md -->
+
+## Branch strategy
+- `main` → production (protected, no direct push)
+- `dev` → integration (protected, PRs only)
+- `feat/{LINEAR-ID}-{slug}` → working branches in worktrees
+
+## Commands
+- Build: `npm run build`
+- Test: `npm test`
+- Type check: `npm run typecheck`
+- Lint: `npm run lint`
+- Dev: `npm run dev`
+
+## Conventions
+<!-- Project-specific. Examples: -->
+- Functional components only, no class components
+- Always handle errors explicitly — no silent catches
+- New API routes must have input validation
+- See `spec/` for full conventions
+
+## Forge principles (auto-applied — see ~/.forge/ETHOS.md)
+1. Boil the Lake — refuse weak inputs
+2. Iron Law of Investigation — no fixes without RCA
+3. Confusion Protocol — clarify, don't guess
+4. Test-or-die — every PR ships with tests
+5. Compound Learning — capture notable learnings
+6. Multi-model Second Opinion — Codex on critical paths
+7. Plan Mode Mandatory — no multi-file changes without /plan-task
+8. 12-Factor Env Discipline — never commit secrets
+
+## Critical paths
+<!-- Files matching these patterns trigger /codex auto-review on /ship -->
+See CRITICAL.md

package/templates/CRITICAL.template.md

@@ -0,0 +1,11 @@
+# Files requiring multi-model review (/codex auto-triggers on /ship)
+# Edit this list to match your project's critical paths
+
+src/lib/auth/**
+src/lib/billing/**
+src/app/api/webhooks/**
+src/app/api/auth/**
+infrastructure/**
+.github/workflows/**
+prisma/schema.prisma
+supabase/migrations/**

package/templates/DESIGN.template.md

@@ -0,0 +1,37 @@
+# {{PROJECT_NAME}} — DESIGN
+
+## Tokens
+<!-- Reference brand assets via @inherit pattern. -->
+
+@inherit ~/{{BRAND_PATH}}/DESIGN-SYSTEM.md#tokens
+
+Project-specific overrides:
+- 
+
+## Components
+<!-- Reference primitives from design-system. List project-specific composites. -->
+
+@inherit ~/{{BRAND_PATH}}/DESIGN-SYSTEM.md#components
+
+Project additions:
+- 
+
+## Layouts
+<!-- Project-unique page templates. -->
+
+## Voice & tone
+@inherit ~/{{BRAND_PATH}}/VOICE.md
+
+Project-specific calibration:
+<!-- Any shifts from brand voice for this product context. -->
+- 
+
+## Accessibility
+- WCAG AA minimum
+- AAA for text contrast
+- All interactive elements have visible focus
+- Keyboard navigation tested
+- Screen reader patterns: 
+
+## States
+<!-- For every interactive element: loading, error, empty, success. -->

package/templates/PRD.template.md

@@ -0,0 +1,30 @@
+# {{PROJECT_NAME}} — PRD
+
+## Problem
+<!-- REQUIRED: Concrete pain, who feels it, when. -->
+
+## Target user
+<!-- REQUIRED: Specific persona, JTBD format. -->
+
+## Acceptance Criteria (the MVP)
+<!-- REQUIRED: Concrete, testable bullets. -->
+- [ ] User can ___
+- [ ] System enforces ___
+- [ ] Performance: ___ in < ___ ms
+- [ ] Accessibility: ___
+
+## Explicit non-goals
+<!-- REQUIRED: Must include all from BRIEF non-goals. -->
+- Not building ___
+- Out of scope: ___
+
+## Success metrics
+<!-- REQUIRED: Must include north-star from BRIEF. -->
+- North-star: ___ (target value, timeframe)
+- Leading indicators: ___, ___, ___
+
+## Constraints
+<!-- REQUIRED: Budget, timeline, regulatory, integration. -->
+
+## User flows
+<!-- For each primary flow: numbered steps + edge cases. -->

package/templates/SPEC.template.md

@@ -0,0 +1,49 @@
+# {{PROJECT_NAME}} — SPEC
+
+## Stack
+<!-- REQUIRED: All choices. -->
+- Runtime: 
+- Frontend: 
+- Backend: 
+- Database: 
+- Hosting: ___ (dev) / ___ (prod)
+- Auth: 
+
+## Data model
+<!-- REQUIRED: Tables/collections with fields, relationships, indexes. -->
+
+```sql
+-- Pseudo-schema or actual DDL
+```
+
+## Key flows
+<!-- For each primary user journey: -->
+
+### Flow 1: ___
+1. User ___
+2. System ___
+3. Edge cases: ___
+
+## Integration points
+<!-- External services: APIs, webhooks, queues. -->
+
+## Security model
+<!-- REQUIRED -->
+- AuthN: 
+- AuthZ: ___ (RLS, RBAC, claims-based?)
+- Sensitive data: ___ (encryption at rest, in transit)
+- Rate limiting: 
+
+## Environment variables
+<!-- REQUIRED: 12-Factor compliant. List with descriptions. -->
+- `DATABASE_URL` — 
+- `API_KEY` — 
+
+## Performance targets
+- p95 page load: 
+- p95 API response: 
+
+## Observability
+- Logs: 
+- Metrics: 
+- Errors: 

package/templates/github-workflows/claude-issue.yml

@@ -0,0 +1,27 @@
+name: Claude — Issue Assistant
+on:
+  issue_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review_comment:
+    types: [created]
+
+jobs:
+  claude:
+    runs-on: ubuntu-latest
+    if: |
+      contains(github.event.comment.body, '@claude') ||
+      (github.event.action == 'assigned' && github.event.assignee.login == 'claude-bot')
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          allowed_tools: "Edit,Read,Bash(git*),Bash(npm run*),Bash(npx tsc*)"

package/templates/github-workflows/claude-pr-review.yml

@@ -0,0 +1,22 @@
+name: Claude — PR Security Review
+on:
+  pull_request:
+    types: [opened, synchronize]
+    branches: [dev, main]
+
+jobs:
+  security-review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.sha }}
+      - uses: anthropics/claude-code-security-review@main
+        with:
+          comment-pr: true
+          claude-api-key: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          fail-on-findings: false

package/templates/github-workflows/claude-scheduled.yml

@@ -0,0 +1,23 @@
+name: Claude — Scheduled Tasks
+on:
+  schedule:
+    - cron: '0 9 * * 1'    # Mondays 9am UTC
+  workflow_dispatch:
+
+jobs:
+  tech-debt:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            Review the codebase for tech debt: duplicated code, dead code,
+            outdated dependencies, missing tests on critical paths.
+            Create branch chore/tech-debt-{date}, propose fixes, open PR to dev.
+          allowed_tools: "Edit,Read,Bash(git*),Bash(npm run*)"

package/templates/github-workflows/test.yml

@@ -0,0 +1,18 @@
+name: Tests
+on:
+  pull_request:
+    branches: [dev, main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run lint
+      - run: npm test

package/templates/learning.template.md

@@ -0,0 +1,14 @@
+# {{TITLE}}
+> {{ISO_DATE}} · {{LINEAR_ID}} · tags: [{{TAGS}}]
+
+## What we expected
+{{EXPECTED}}
+
+## What happened
+{{ACTUAL}}
+
+## Why
+{{ROOT_CAUSE}}
+
+## Next time
+{{DIFFERENT_APPROACH}}

package/templates/phases.template.yaml

@@ -0,0 +1,45 @@
+project: "{{PROJECT_NAME}}"
+linear_project_id: ""    # populated by /push-to-linear
+linear_team_id: ""       # populated by /push-to-linear
+github_repo: ""          # populated by /setup-repo
+gate_check_command: "npm run e2e && npm run typecheck && npm run lint"
+
+phases:
+  - id: phase-1
+    name: "Foundations"
+    status: active
+    goal: "Working skeleton end-to-end with seed data"
+    gate_criteria:
+      - "All P0 + P1 tasks closed in Linear"
+      - "Dev deploy succeeds"
+      - "No P0 bugs open"
+    tasks:
+      - id: P1-T01
+        linear_id: ""    # populated by /push-to-linear
+        title: ""
+        description: ""
+        type: foundation
+        priority: P0
+        depends_on: []
+        estimate: M
+        owner_type: backend-dev
+        acceptance:
+          - ""
+
+  - id: phase-2
+    name: "Core Features"
+    status: blocked
+    blocked_by: phase-1
+    goal: ""
+    gate_criteria:
+      - ""
+    tasks: []
+
+  - id: phase-3
+    name: "Polish & Launch"
+    status: blocked
+    blocked_by: phase-2
+    goal: ""
+    gate_criteria:
+      - ""
+    tasks: []

package/templates/retro.template.md

@@ -0,0 +1,27 @@
+# {{PROJECT_NAME}} — Phase {{N}} Retro
+> Closed: {{ISO_DATE}}
+
+## What shipped
+- {{COUNT}} tasks closed
+- Highlights:
+
+## Cycle metrics
+- Avg cycle time: {{AVG_HOURS}} hours
+- Tasks at P0: {{P0_COUNT}}
+- Bugs found post-merge: {{BUG_COUNT}}
+
+## Decisions made
+- {{DECISION}} (PR #{{PR}})
+
+## Scope changes from original phases.yaml
+- Added: 
+- Removed: 
+- Re-prioritized: 
+
+## Learnings harvested
+- `docs/learnings/{{Q}}/{{LEARNING_SLUG}}.md`
+
+## Different next phase
+1. 
+2. 
+3.