@harness-engineering/cli 1.12.0 → 1.13.1

package/dist/agents/skills/claude-code/harness-auth/SKILL.md

@@ -0,0 +1,279 @@
+# Harness Auth
+
+> OAuth2, JWT, RBAC/ABAC, session management, and MFA pattern analysis. Detects authentication and authorization mechanisms, evaluates security posture against OWASP guidelines, and recommends improvements for token lifecycle, permission models, and multi-factor authentication.
+
+## When to Use
+
+- When implementing or modifying authentication flows (login, registration, password reset, OAuth2)
+- On PRs that change authorization logic, middleware guards, or permission models
+- To audit existing auth implementation for security vulnerabilities and best practice compliance
+- NOT for network-level security or infrastructure hardening (use harness-security-review)
+- NOT for compliance framework audits (use harness-compliance for SOC2/HIPAA/GDPR)
+- NOT for secrets management or credential rotation (use harness-secrets)
+
+## Process
+
+### Phase 1: DETECT -- Identify Auth Mechanisms and Providers
+
+1. **Discover authentication providers.** Scan the codebase for auth framework usage:
+   - Passport.js: `passport.use()`, strategy configurations, `passport.authenticate()` calls
+   - NextAuth.js / Auth.js: `next-auth` config, provider definitions, callback handlers
+   - Auth0: `@auth0/nextjs-auth0`, `auth0-js`, management API client initialization
+   - Firebase Auth: `firebase/auth`, `signInWithPopup`, `onAuthStateChanged` usage
+   - Custom: JWT signing/verification, bcrypt hashing, session store initialization
+   - Spring Security: `@EnableWebSecurity`, `SecurityFilterChain`, `UserDetailsService`
+   - ASP.NET Identity: `AddAuthentication()`, `[Authorize]` attributes, `ClaimsPrincipal`
+
+2. **Map token flows.** Trace the authentication lifecycle:
+   - Token issuance: Where and how are JWTs or session tokens created?
+   - Token storage: Cookie (httpOnly, secure, sameSite?), localStorage, sessionStorage, or in-memory?
+   - Token refresh: Is there a refresh token flow? What is the access token lifetime?
+   - Token revocation: Can tokens be invalidated before expiry? Is there a blocklist?
+   - Token propagation: How are tokens passed between services (Authorization header, cookie, custom header)?
+
+3. **Identify authorization models.** Determine how permissions are enforced:
+   - RBAC: Role definitions, role-to-permission mappings, role assignment to users
+   - ABAC: Attribute-based policies, policy evaluation engine, context attributes
+   - ACL: Per-resource access control lists, ownership checks
+   - Middleware guards: Express middleware, NestJS guards, Spring interceptors, ASP.NET policies
+   - Route-level: Declarative route protection, public vs protected route definitions
+
+4. **Check for MFA implementation.** Look for multi-factor authentication:
+   - TOTP: `otplib`, `speakeasy`, Google Authenticator integration
+   - SMS/Email OTP: Twilio, SendGrid verification flows
+   - WebAuthn/FIDO2: `@simplewebauthn/server`, hardware key registration
+   - Recovery codes: Generation, storage, and redemption logic
+
+5. **Inventory session management.** If sessions are used:
+   - Session store: Redis, database, in-memory, or cookie-based
+   - Session lifecycle: creation, renewal, expiry, and destruction
+   - Concurrent session handling: single-session enforcement, session listing
+
+---
+
+### Phase 2: ANALYZE -- Evaluate Security Posture
+
+1. **Check JWT implementation against OWASP guidelines.** Verify:
+   - Algorithm is explicitly set (no `alg: none` vulnerability)
+   - Secret/key is sufficiently strong (RS256/ES256 preferred over HS256 for distributed systems)
+   - Token lifetime is appropriate (access: 15-60 min, refresh: 7-30 days)
+   - Claims include `iss`, `aud`, `exp`, `iat`, and `sub` at minimum
+   - Tokens are validated on every request, not just on login
+   - JWTs are not stored in localStorage (XSS vulnerability)
+
+2. **Evaluate OAuth2/OIDC flows.** If OAuth2 is used:
+   - Is PKCE used for public clients (SPAs, mobile apps)?
+   - Are redirect URIs strictly validated (no open redirect)?
+   - Is the state parameter used to prevent CSRF?
+   - Are scopes minimized to the principle of least privilege?
+   - Is token exchange happening server-side (not exposing client secret)?
+
+3. **Assess password handling.** If password authentication exists:
+   - Hashing algorithm: bcrypt, scrypt, or argon2 (not MD5, SHA-1, or SHA-256 without salt)
+   - Salt: unique per user, generated with cryptographic RNG
+   - Password policy: minimum length, complexity requirements, breach database check
+   - Rate limiting on login attempts (brute force protection)
+   - Account lockout or CAPTCHA after failed attempts
+
+4. **Review authorization enforcement.** For each protected resource:
+   - Is authorization checked at the API layer (not just the UI)?
+   - Are there IDOR (Insecure Direct Object Reference) vulnerabilities?
+   - Is the permission check granular enough (not just "is authenticated")?
+   - Are admin routes protected by role checks, not just authentication?
+   - Is horizontal privilege escalation prevented (user A cannot access user B's data)?
+
+5. **Check session security.** If sessions are used:
+   - Session ID entropy: cryptographically random, sufficient length
+   - Cookie flags: `httpOnly`, `secure`, `sameSite=Strict` or `sameSite=Lax`
+   - Session fixation prevention: regenerate ID on login
+   - Session timeout: absolute and idle timeout configured
+   - CSRF protection: token-based or SameSite cookie
+
+---
+
+### Phase 3: DESIGN -- Recommend Improvements
+
+1. **Token lifecycle improvements.** Based on analysis findings:
+   - Recommend specific token lifetimes with rationale
+   - Design refresh token rotation (one-time-use refresh tokens with family tracking)
+   - Propose token revocation strategy (blocklist in Redis with TTL matching token expiry)
+   - If using JWTs in cookies: recommend cookie configuration (httpOnly, secure, sameSite, path, domain)
+
+2. **Permission model design.** Based on the application's needs:
+   - For simple apps: RBAC with predefined roles (admin, editor, viewer)
+   - For multi-tenant apps: RBAC with tenant-scoped roles
+   - For complex resource access: ABAC with policy engine (CASL, Casbin, Open Policy Agent)
+   - Generate permission matrix: roles/attributes x resources x actions
+
+3. **MFA implementation plan.** If MFA is missing or incomplete:
+   - Recommend TOTP as baseline (widely supported, no SMS dependency)
+   - Design enrollment flow: QR code generation, backup codes, verification step
+   - Design authentication flow: primary factor -> MFA challenge -> session creation
+   - Recommend WebAuthn as optional upgrade path for phishing resistance
+
+4. **Security hardening recommendations.** Prioritized by risk:
+   - P0: Fix any authentication bypass, broken access control, or token vulnerability
+   - P1: Add missing CSRF protection, fix insecure token storage, add rate limiting
+   - P2: Implement MFA, add session management improvements, enhance logging
+   - P3: Add breach notification flow, implement progressive security (step-up auth)
+
+5. **Generate implementation guidance.** Produce:
+   - Middleware/guard code templates for the project's framework
+   - Migration plan for moving from insecure to secure token storage
+   - Database schema for RBAC tables (users, roles, permissions, user_roles)
+   - Configuration templates for OAuth2 providers
+
+---
+
+### Phase 4: VALIDATE -- Verify Against OWASP and Common Vulnerabilities
+
+1. **OWASP Authentication Verification.** Check against OWASP ASVS (Application Security Verification Standard) Level 2:
+   - V2.1: Password security (hashing, policy, breach check)
+   - V2.2: General authenticator security (MFA, recovery codes)
+   - V2.5: Credential recovery (secure reset flow, no secret questions)
+   - V2.7: Out-of-band verification (email/SMS verification security)
+   - V2.8: Single or multi-factor authentication (session binding)
+
+2. **OWASP Authorization Verification.** Check against OWASP ASVS:
+   - V4.1: Access control design (deny by default, least privilege)
+   - V4.2: Operation-level access control (every API endpoint protected)
+   - V4.3: Data-level access control (row-level security, tenant isolation)
+
+3. **Test coverage verification.** Check that auth logic is tested:
+   - Authentication tests: valid login, invalid credentials, expired tokens, refresh flow
+   - Authorization tests: permitted access, denied access, privilege escalation attempt
+   - Edge cases: expired session, concurrent sessions, token replay, CSRF
+   - Integration tests: full OAuth2 flow with mocked provider
+
+4. **Verify logging and monitoring.** Confirm security events are logged:
+   - Successful and failed login attempts with timestamps and IP addresses
+   - Password changes and account recovery events
+   - Permission changes and role assignments
+   - Token refresh and revocation events
+   - Log format must not include passwords, tokens, or session IDs
+
+5. **Produce the auth audit report.** Output a structured summary:
+   - Authentication mechanism inventory
+   - OWASP ASVS compliance status by section
+   - Prioritized findings with severity and remediation
+   - Permission model diagram or matrix
+   - Recommended implementation timeline
+
+---
+
+## Harness Integration
+
+- **`harness skill run harness-auth`** -- Primary CLI entry point. Runs all four phases.
+- **`harness validate`** -- Run after implementing auth changes to verify project integrity.
+- **`harness check-deps`** -- Verify auth library dependencies are properly declared and up to date.
+- **`emit_interaction`** -- Used at permission model design (checkpoint:decision) when choosing between RBAC and ABAC, and before recommending OAuth2 provider changes.
+- **`Glob`** -- Discover auth middleware, guard files, policy definitions, and session configurations.
+- **`Grep`** -- Search for JWT signing, password hashing, token validation, and authorization checks.
+- **`Write`** -- Generate permission matrices, migration plans, and middleware templates.
+- **`Edit`** -- Update existing auth middleware, guards, and token configurations.
+
+## Success Criteria
+
+- All authentication providers and token flows are mapped with specific file locations
+- JWT implementation is checked against all OWASP ASVS V2 requirements
+- Authorization model is documented with a permission matrix covering all roles and resources
+- Every finding includes a severity level, specific file location, and concrete remediation step
+- Token storage recommendations specify exact cookie flags or storage mechanism
+- Security event logging is verified to capture auth events without leaking sensitive data
+
+## Examples
+
+### Example: Next.js Application with NextAuth.js and Prisma
+
+```
+Phase 1: DETECT
+  Provider: NextAuth.js v4 in src/app/api/auth/[...nextauth]/route.ts
+  Strategies: Google OAuth2, GitHub OAuth2, email/password (credentials provider)
+  Token flow: JWT mode, access token in httpOnly cookie, 30-day expiry
+  Authorization: Custom middleware in src/middleware.ts checking session.user.role
+  Roles: admin, member (stored in User table via Prisma)
+  MFA: Not implemented
+  Session store: JWT-based (no server-side session)
+
+Phase 2: ANALYZE
+  Findings:
+    [HIGH] JWT expiry 30 days is excessive — recommend 1 hour with refresh token
+    [HIGH] Credentials provider uses bcrypt cost factor 8 — recommend 12
+    [MEDIUM] No PKCE on OAuth2 flows (NextAuth handles this but verify config)
+    [MEDIUM] No rate limiting on /api/auth/callback/credentials
+    [LOW] Role check only in middleware — no API-level authorization guards
+    [LOW] No audit logging for login events
+
+Phase 3: DESIGN
+  Recommendations:
+    1. Switch to database sessions with 1-hour access, 7-day refresh
+    2. Increase bcrypt rounds to 12 in credentials provider
+    3. Add rate-limiter-flexible middleware on auth endpoints (5 attempts/15min)
+    4. Create src/lib/guards/requireRole.ts middleware for API routes
+    5. Add TOTP MFA via otplib with QR enrollment flow
+    6. Add auth event logging to audit table via Prisma middleware
+
+Phase 4: VALIDATE
+  OWASP ASVS V2 status:
+    V2.1 Password Security: PARTIAL (hashing OK, cost factor low, no breach check)
+    V2.2 Authenticator Security: FAIL (no MFA)
+    V2.5 Credential Recovery: PASS (email-based reset via NextAuth)
+    V4.1 Access Control Design: PARTIAL (roles exist, enforcement incomplete)
+  Test coverage: 60% — missing tests for role escalation and token expiry
+```
+
+### Example: NestJS API with Passport.js, JWT, and CASL
+
+```
+Phase 1: DETECT
+  Provider: Passport.js with passport-jwt and passport-local strategies
+  Token flow:
+    - Access token: RS256 JWT, 15-min expiry, in Authorization header
+    - Refresh token: opaque, 30-day expiry, in httpOnly cookie
+    - Token refresh endpoint: POST /auth/refresh
+  Authorization: CASL abilities defined in src/casl/ability.factory.ts
+  Roles: super-admin, org-admin, member, viewer (stored in PostgreSQL)
+  MFA: TOTP via speakeasy, WebAuthn via @simplewebauthn/server
+  Session: Stateless JWT (no server-side session)
+
+Phase 2: ANALYZE
+  Findings:
+    [HIGH] Refresh token not rotated on use — token replay possible
+    [MEDIUM] CASL abilities not checked on 3 admin endpoints (src/admin/admin.controller.ts)
+    [MEDIUM] No token blocklist — revoked tokens valid until expiry
+    [LOW] WebAuthn registration does not verify attestation
+    [LOW] Login failure logging does not include client IP
+
+Phase 3: DESIGN
+  Recommendations:
+    1. Implement refresh token rotation with family tracking in Redis
+       - On refresh: invalidate old token, issue new pair
+       - On reuse of old token: revoke entire token family (detect theft)
+    2. Add @CheckPolicies() decorator to admin.controller.ts endpoints
+    3. Add Redis-backed token blocklist with TTL = access token lifetime
+    4. Add attestation verification for WebAuthn with expected origin check
+    5. Enhance auth logging with IP, user-agent, and geolocation
+
+Phase 4: VALIDATE
+  OWASP ASVS V2 status:
+    V2.1 Password Security: PASS
+    V2.2 Authenticator Security: PASS (TOTP + WebAuthn)
+    V2.8 Multi-Factor: PASS
+    V4.1 Access Control: PARTIAL (CASL defined, 3 endpoints uncovered)
+    V4.3 Data-Level: PASS (CASL policies include tenant isolation)
+  Test coverage: 85% — missing tests for token family revocation
+```
+
+## Gates
+
+- **No authentication bypass findings left unresolved.** Any finding that allows unauthenticated access to a protected resource is a P0 blocker. The auth audit cannot be marked complete while bypass vulnerabilities exist.
+- **No tokens stored in localStorage.** JWTs or session tokens in localStorage are accessible via XSS. This is a blocking finding. Tokens must be stored in httpOnly cookies or secure server-side sessions.
+- **No plaintext or weakly hashed passwords.** MD5, SHA-1, or unsalted SHA-256 for password storage is a blocking finding. Passwords must use bcrypt (cost 12+), scrypt, or argon2id.
+- **No authorization checks skipped at the API layer.** UI-only authorization is not authorization. Every API endpoint that serves user-specific or role-restricted data must enforce permissions server-side.
+
+## Escalation
+
+- **When the auth architecture requires a fundamental redesign:** Report: "The current auth implementation has [N] high-severity findings that require architectural changes (e.g., switching from localStorage tokens to httpOnly cookies). This is not a patch — recommend a dedicated auth migration sprint with a rollback plan."
+- **When third-party auth provider documentation is insufficient:** Report: "The [provider] SDK does not document [specific behavior]. Recommend testing the behavior empirically in a sandbox environment and documenting the findings in the project's auth architecture doc."
+- **When MFA adoption requires UX changes beyond the auth layer:** Report: "Implementing MFA requires changes to [login flow, account settings, recovery flow]. Coordinate with the frontend team to design the enrollment and challenge UX before implementing the backend."
+- **When the permission model is too simple for current requirements:** Report: "The current RBAC model with [N] roles cannot express [specific access pattern]. Recommend evaluating ABAC with [CASL/Casbin/OPA] to support attribute-based policies. This is a significant migration — plan for 2-3 sprints."

package/dist/agents/skills/claude-code/harness-auth/skill.yaml

@@ -0,0 +1,81 @@
+name: harness-auth
+version: "1.0.0"
+description: OAuth2, JWT, RBAC/ABAC, session management, and MFA patterns
+cognitive_mode: advisory-guide
+triggers:
+  - manual
+  - on_new_feature
+  - on_pr
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - emit_interaction
+cli:
+  command: harness skill run harness-auth
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: focus
+      description: "Auth area to focus on: authn, authz, session, mfa, or all. Defaults to all."
+      required: false
+    - name: framework
+      description: "Auth framework in use: passport, next-auth, auth0, firebase-auth, or custom. Auto-detected when omitted."
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-auth
+    path: string
+type: rigid
+tier: 3
+internal: false
+keywords:
+  - auth
+  - authentication
+  - authorization
+  - OAuth2
+  - JWT
+  - RBAC
+  - ABAC
+  - session
+  - MFA
+  - OIDC
+  - SSO
+  - SAML
+  - passport
+  - token
+  - refresh token
+  - PKCE
+stack_signals:
+  - "src/**/auth/**"
+  - "src/**/middleware/auth*"
+  - "src/**/*passport*"
+  - "src/**/*jwt*"
+  - "src/**/*session*"
+  - "src/**/guards/**"
+  - "src/**/policies/**"
+phases:
+  - name: detect
+    description: Identify authentication and authorization mechanisms, providers, and token flows
+    required: true
+  - name: analyze
+    description: Evaluate security posture, token lifecycle, permission models, and session handling
+    required: true
+  - name: design
+    description: Recommend improvements for auth flows, RBAC/ABAC models, and MFA integration
+    required: true
+  - name: validate
+    description: Verify auth implementation against OWASP guidelines and common vulnerability patterns
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/harness-autopilot/SKILL.md

@@ -102,20 +102,26 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
      path: "<project-root>",
      intent: "Autopilot phase execution for <spec name>",
      skill: "harness-autopilot",
+     session: "<session-slug>",
      include: ["state", "learnings", "handoff", "validation"]
    })
    ```
 
-   This loads learnings (including failure entries tagged `[outcome:failure]`), handoff context, state, and validation results in a single call. Note any relevant learnings or known dead ends for the current phase from the returned `learnings` array.
+   This loads session-scoped learnings, handoff, state, and validation results in a single call. The `session` parameter ensures all reads come from the session directory (`.harness/sessions/<slug>/`), isolating this workstream from others. Note any relevant learnings or known dead ends for the current phase from the returned `learnings` array.
 
-6. **Load roadmap context.** If `docs/roadmap.md` exists, read it to understand:
+6. **Load session summary for cold start.** If resuming (existing `autopilot-state.json` found):
+   - Call `loadSessionSummary()` for the session slug to get quick orientation context (~200 tokens).
+   - The summary provides the last skill, phase, status, and next step — enough to understand where the autopilot left off without re-reading the full state machine.
+   - If no summary exists (first run), skip — the full INIT handles context loading.
+
+7. **Load roadmap context.** If `docs/roadmap.md` exists, read it to understand:
    - Current project priorities (which features are `in-progress`)
    - Blockers that may affect the upcoming phases
    - Overall project status and milestone progress
 
    This provides the autopilot with project-level context beyond the individual spec being executed. If the roadmap does not exist, skip this step — the autopilot operates normally without it.
 
-7. **Transition to ASSESS.**
+8. **Transition to ASSESS.**
 
 ---
 
@@ -155,9 +161,11 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
        Spec: {specPath}
        Session directory: {sessionDir}
+       Session slug: {sessionSlug}
        Phase description: {phase description from spec}
-       Previous phase learnings (global): {relevant learnings from .harness/learnings.md}
-       Known failures to avoid (global): {relevant entries from .harness/failures.md}
+
+       On startup, call gather_context({ session: "{sessionSlug}" }) to load
+       session-scoped learnings, state, and validation context.
 
        Follow the harness-planning skill process exactly. Write the plan to
        docs/plans/{date}-{phase-name}-plan.md. Write {sessionDir}/handoff.json when done.
@@ -221,9 +229,11 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
        Plan: {planPath}
        Session directory: {sessionDir}
+       Session slug: {sessionSlug}
        State: {sessionDir}/state.json
-       Learnings (global): .harness/learnings.md
-       Failures (global): .harness/failures.md
+
+       On startup, call gather_context({ session: "{sessionSlug}" }) to load
+       session-scoped learnings, state, and validation context.
 
        Follow the harness-execution skill process exactly.
        Update {sessionDir}/state.json after each task.
@@ -268,6 +278,10 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
        You are running harness-verification for phase {N}: {name}.
 
        Session directory: {sessionDir}
+       Session slug: {sessionSlug}
+
+       On startup, call gather_context({ session: "{sessionSlug}" }) to load
+       session-scoped learnings, state, and validation context.
 
        Follow the harness-verification skill process exactly.
        Report pass/fail with findings.
@@ -296,6 +310,10 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
        You are running harness-code-review for phase {N}: {name}.
 
        Session directory: {sessionDir}
+       Session slug: {sessionSlug}
+
+       On startup, call gather_context({ session: "{sessionSlug}" }) to load
+       session-scoped learnings, state, and validation context.
 
        Follow the harness-code-review skill process exactly.
        Report findings with severity (blocking / warning / note).
@@ -341,7 +359,23 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 4. **Sync roadmap.** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true`. This reflects the just-completed phase in the roadmap (e.g., updating the feature from `planned` to `in-progress`). If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core. Skip silently if no roadmap exists. Do not use `force_sync: true` — the human-always-wins rule applies.
 
-5. **Check for next phase:**
+5. **Write session summary.** Update the session summary to reflect the completed phase:
+
+   ```json
+   writeSessionSummary(projectPath, sessionSlug, {
+     session: "<session-slug>",
+     lastActive: "<ISO timestamp>",
+     skill: "harness-autopilot",
+     phase: "<completed phase number> of <total phases>",
+     status: "Phase <N> complete. <tasks completed>/<total> tasks.",
+     spec: "<spec path>",
+     plan: "<current plan path>",
+     keyContext: "<1-2 sentences: what this phase accomplished, key decisions>",
+     nextStep: "<e.g., Continue to Phase N+1: <name>, or DONE>"
+   })
+   ```
+
+6. **Check for next phase:**
    - If more phases remain: "Phase {N} complete. Next: Phase {N+1}: {name} (complexity: {level}). Continue? (yes / stop)"
      - **yes** — Increment `currentPhase`, reset `retryBudget`, transition to ASSESS.
      - **stop** — Save state and exit.
@@ -387,7 +421,21 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 5. **Update roadmap to done.** If `docs/roadmap.md` exists and the current spec maps to a roadmap feature, call `manage_roadmap` with action `update` to set the feature status to `done`. Derive the feature name from the spec title (H1 heading) or the session's `handoff.json` `summary` field. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `updateFeature()` from core. Skip silently if no roadmap exists or if the feature is not found. Do not use `force_sync: true`.
 
-6. **Clean up state:** Set `currentState: "DONE"` in `{sessionDir}/autopilot-state.json`. Do not delete the file — it serves as a record.
+6. **Write final session summary.** Update the session summary to reflect completion:
+
+   ```json
+   writeSessionSummary(projectPath, sessionSlug, {
+     session: "<session-slug>",
+     lastActive: "<ISO timestamp>",
+     skill: "harness-autopilot",
+     status: "DONE. <total phases> phases, <total tasks> tasks complete.",
+     spec: "<spec path>",
+     keyContext: "<1-2 sentences: overall summary of what was built>",
+     nextStep: "All phases complete. Create PR or close session."
+   })
+   ```
+
+7. **Clean up state:** Set `currentState: "DONE"` in `{sessionDir}/autopilot-state.json`. Do not delete the file — it serves as a record.
 
 ## Harness Integration
 

package/dist/agents/skills/claude-code/harness-autopilot/skill.yaml

@@ -29,6 +29,7 @@ mcp:
     skill: harness-autopilot
     path: string
 type: rigid
+tier: 1
 phases:
   - name: init
     description: Load spec, identify phases, restore state if resuming

package/dist/agents/skills/claude-code/harness-brainstorming/SKILL.md

@@ -161,7 +161,7 @@ These keywords flow into the `handoff.json` `contextKeywords` field when the spe
    - Call `manage_roadmap` with action `add`, `status: "planned"`, `milestone: "Current Work"`, and the spec path. Include a one-line summary from the spec overview.
    - If the feature already exists in the roadmap (duplicate name), skip silently — the feature was likely added manually or by a prior brainstorming session.
    - Log: `"Added '<feature-name>' to roadmap as planned"` (informational, not a prompt).
-   - If `manage_roadmap` is unavailable, fall back to direct file manipulation using `addFeature()` from core.
+   - If `manage_roadmap` is unavailable, fall back to direct file manipulation using `parseRoadmap`/`serializeRoadmap` from core to read, modify, and write `docs/roadmap.md`.
    - If no roadmap exists, skip this step silently.
 
 7. **Write handoff and suggest transition.** After the human approves the spec:

package/dist/agents/skills/claude-code/harness-brainstorming/skill.yaml

@@ -28,6 +28,7 @@ mcp:
     skill: harness-brainstorming
     path: string
 type: rigid
+tier: 1
 phases:
   - name: explore
     description: Generate ideas and possibilities