diff --git a/spec/README.md b/spec/README.md index 37d46e9..a5b8c23 100644 --- a/spec/README.md +++ b/spec/README.md @@ -5,7 +5,6 @@ This system combines the best practices from Context Engineering (Cole Medin), 3 ## Quick Start 1. **Create a specification** - ```bash mkdir -p spec/my-feature cp spec/template.md spec/my-feature/spec.md @@ -13,21 +12,18 @@ This system combines the best practices from Context Engineering (Cole Medin), 3 ``` 2. **Generate implementation plan** - ``` /plan my-feature # or just: /plan (auto-detects if only one spec) ``` 3. **Build the feature** - ``` /build # Auto-detects the spec with plan.md ``` 4. **Validate readiness** - ``` /check ``` @@ -80,45 +76,37 @@ This system is built on three core principles: ## Workflow Overview ### 1. Specification (Human writes) - Define WHAT needs to be built, not HOW. Include: - - Clear outcome and success criteria - Examples and references - Constraints and context ### 2. Planning (AI generates) - AI analyzes the spec and creates detailed implementation plan: - - Task breakdown - Risk assessment - Validation steps ### 3. Building (AI executes) - AI implements based on plan with: - - Continuous validation - Progress tracking - Error recovery ### 4. Shipping (AI completes) - Final validation and PR preparation: - - Comprehensive checks - Documentation updates - Clean git history ## Command Reference -| Command | Purpose | Notes | -| -------- | -------------------------------- | ----------------------------------------- | -| `/plan` | Generate implementation plan | Auto-detects spec or accepts fragment | -| `/build` | Execute implementation | Validates continuously; full suite at end | -| `/check` | Validate PR readiness (optional) | /ship runs this automatically | -| `/ship` | Complete and ship | Creates PR; runs /check first | +| Command | Purpose | Notes | +|---------|---------|-------| +| `/plan` | Generate implementation plan | Auto-detects spec or accepts fragment | +| `/build` | Execute implementation | Validates continuously; full suite at end | +| `/check` | Validate PR readiness (optional) | /ship runs this automatically | +| `/ship` | Complete and ship | Creates PR; runs /check first | ## Feature Lifecycle & Cleanup Workflow @@ -127,13 +115,11 @@ Final validation and PR preparation: CSW uses **rebase workflow** (linear history), not merge commits. **When you run `/ship`**: - 1. Creates PR from feature branch 2. Commits and pushes to remote 3. PR is ready for review and merge **When you run `/cleanup` (after PR is merged)**: - 1. Syncs with main branch 2. Deletes merged feature branches 3. Creates `cleanup/merged` staging branch @@ -141,7 +127,6 @@ CSW uses **rebase workflow** (linear history), not merge commits. 5. Commits the cleanup **When you run `/plan` (next feature)**: - 1. Detects `cleanup/merged` branch and renames it to new feature name 2. Or creates new feature branch from main 3. Ready to start next feature @@ -149,7 +134,6 @@ CSW uses **rebase workflow** (linear history), not merge commits. ### Cleanup = DELETE The `/cleanup` command deletes shipped specs from your working tree: - 1. Finds all spec directories with `log.md` files 2. **DELETES** those spec directories (`spec/feature-name/`) 3. Commits the deletion on `cleanup/merged` branch @@ -184,7 +168,6 @@ sequenceDiagram ### Path Simplification Paths simplified from `spec/active/feature/` to `spec/feature/`: - - Old: `spec/active/authentication/spec.md` - New: `spec/authentication/spec.md` @@ -193,13 +176,11 @@ Paths simplified from `spec/active/feature/` to `spec/feature/`: ### Arbitrary Nesting After `spec/`, organize however you want: - - **Flat**: `spec/auth/`, `spec/dashboard/` - **By layer**: `spec/frontend/auth/`, `spec/backend/users/` - **By team**: `spec/team-a/feature-x/`, `spec/team-b/feature-y/` **Feature identity** = full relative path under spec/: - - `spec/auth/` → feature: `"auth"` - `spec/frontend/auth/` → feature: `"frontend/auth"` - `spec/team-a/feature-x/` → feature: `"team-a/feature-x"` @@ -209,14 +190,12 @@ After `spec/`, organize however you want: Commands accept fragments, not full paths: **Zero arguments** (auto-detect): - ```bash /plan # Auto-detects if only 1 spec exists /build # Auto-detects if only 1 plan exists ``` **Fragment matching** (Claude fuzzy matches): - ```bash /plan auth # Matches spec/auth/ or spec/frontend/auth/ /plan frontend # Matches spec/frontend/auth/ @@ -224,18 +203,15 @@ Commands accept fragments, not full paths: ``` **How it works** (separation of concerns): - 1. **Bash layer**: Runs `find spec/ -name "spec.md"`, returns ALL matches 2. **Claude layer**: Fuzzy matches your fragment, handles disambiguation **Command-specific filtering**: - - `/plan` → Looks for `spec.md` files (specs ready to plan) - `/build` → Looks for `plan.md` files (specs ready to build) - `/ship` → Looks for `plan.md` files (specs ready to ship) **Interactive disambiguation**: Multiple matches show numbered list: - ``` I found 2 specs matching "auth": 1. frontend/auth @@ -248,7 +224,6 @@ You can respond with: `1`, `frontend`, or `the frontend one`. ### Zero-Arg Sequential Workflow Solo development with single feature needs zero path arguments: - ```bash /spec my-feature # Create spec/my-feature/ /plan # Auto-detect (only 1 spec) @@ -261,7 +236,6 @@ Solo development with single feature needs zero path arguments: ## Best Practices ### DO: - - ✅ Write clear, specific requirements - ✅ Include examples from the codebase - ✅ Reference documentation @@ -269,7 +243,6 @@ Solo development with single feature needs zero path arguments: - ✅ Use semantic commit messages ### DON'T: - - ❌ Mix multiple features in one spec - ❌ Skip validation steps - ❌ Ignore failing tests @@ -279,7 +252,6 @@ Solo development with single feature needs zero path arguments: ## Validation Standards All features must pass validation commands defined in `spec/stack.md`: - - **Lint** - No linting errors - **Typecheck** - No type errors (if applicable to your stack) - **Test** - All tests passing @@ -298,19 +270,16 @@ The specific commands depend on your tech stack. See `spec/stack.md` for your pr ## Troubleshooting **Build fails validation?** - - Check log.md for specific errors - Fix the code, not the tests - Re-run validation **Can't ship?** - - Run `/check` for detailed report - Fix all critical issues - Try again **Lost context?** - - Check log.md for progress - Plan.md has the full strategy - Resume from last completed task diff --git a/spec/content-migration-phase3/log.md b/spec/content-migration-phase3/log.md deleted file mode 100644 index e927cb6..0000000 --- a/spec/content-migration-phase3/log.md +++ /dev/null @@ -1,254 +0,0 @@ -# Build Log: Content Migration Phase 3 - -## Session: 2025-10-20 - -Starting task: 1 -Total tasks: 7 - ---- - -### Task 1: Create BaseLayout Component - -Started: 2025-10-20 03:20:00 -File: src/layouts/BaseLayout.astro - -**Implementation**: - -- Created reusable BaseLayout component with Header, Footer, SEO metadata -- Props: title, description, ogImage (optional, defaults to /images/opengraph-image.png) -- Includes Alpine.js script for Header mobile menu -- Follows pattern from src/pages/index.astro (lines 1-40) - -**Validation**: - -- ✅ pnpm lint: Passed -- ✅ pnpm typecheck: 0 errors -- ✅ pnpm build: Completed successfully - -Status: ✅ Complete -Completed: 2025-10-20 03:20:33 - ---- - -### Task 2: Create Blog Placeholder Page - -Started: 2025-10-20 03:21:00 -File: src/pages/blog/index.astro - -**Implementation**: - -- Created blog placeholder "Coming Soon" page using BaseLayout -- Clean messaging about upcoming content (RFID tracking, tag management) -- "Back to Home" button with DaisyUI btn-primary styling -- SEO metadata for blog page - -**Validation**: - -- ✅ pnpm lint: Passed -- ✅ pnpm typecheck: 0 errors, 12 files checked -- ✅ pnpm build: Completed successfully -- ✅ dist/blog/index.html generated - -Status: ✅ Complete -Completed: 2025-10-20 03:21:16 - ---- - -### Task 3: Create Privacy Policy Page - -Started: 2025-10-20 03:21:30 -File: src/pages/privacy-policy.astro - -**Implementation**: - -- Created Privacy Policy page using BaseLayout -- Migrated content from /home/mike/trakrf-web/app/privacy-policy/page.tsx (lines 60-104) -- ✅ CRITICAL FIX: marc@trakrf.id → support@trakrf.id (line 100) -- ✅ Updated date: 2023-08-25 → 2025-10-20 -- "Back" button with DaisyUI btn-ghost styling -- SEO metadata for privacy page - -**Validation**: - -- ✅ pnpm lint: Passed -- ✅ pnpm typecheck: 0 errors, 13 files checked -- ✅ pnpm build: Completed successfully -- ✅ dist/privacy-policy/index.html generated - -Status: ✅ Complete -Completed: 2025-10-20 03:22:09 - ---- - -### Task 4: Create Terms of Service Page - -Started: 2025-10-20 03:22:20 -File: src/pages/tos.astro - -**Implementation**: - -- Created Terms of Service page using BaseLayout -- Migrated content from /home/mike/trakrf-web/app/tos/page.tsx (lines 60-92) -- ✅ CRITICAL FIX: marc@shipfa.st → support@trakrf.id (line 90) -- ✅ Updated date: September 26, 2023 → October 20, 2025 -- ✅ Governing law change: France → United States of America (line 84) -- "Back" button with DaisyUI btn-ghost styling -- SEO metadata for TOS page - -**Validation**: - -- ✅ pnpm lint: Passed -- ✅ pnpm typecheck: 0 errors, 14 files checked -- ✅ pnpm build: Completed successfully -- ✅ dist/tos/index.html generated -- ✅ All 4 pages now built: index, blog, privacy-policy, tos - -Status: ✅ Complete -Completed: 2025-10-20 03:23:03 - ---- - -### Task 5: Add Blog Link to Footer - -Started: 2025-10-20 03:23:20 -File: src/components/Footer.astro - -**Implementation**: - -- Added blog link to Footer LINKS section (line 44) -- Positioned alongside Support and Pricing links -- Uses consistent link-hover link styling -- Links to /blog placeholder page - -**Validation**: - -- ✅ pnpm lint: Passed -- ✅ pnpm typecheck: 0 errors, 14 files checked -- ✅ pnpm build: Completed successfully -- ✅ All 4 pages rebuilt with blog link in footer - -Status: ✅ Complete -Completed: 2025-10-20 03:24:04 - ---- - -### Task 6: Test Multi-Page Navigation - -Started: 2025-10-20 03:24:10 -File: N/A (verification testing) - -**Testing**: - -- ✅ Dev server started on http://localhost:4322/ -- ✅ Blog links verified in all pages (index, blog, tos, privacy-policy) -- ✅ Privacy policy links verified in all pages -- ✅ TOS links verified in all pages -- ✅ "Back to Home" button verified in blog page -- ✅ All navigation links present and correctly formatted -- ✅ Header/Footer components rendering on all pages - -**Verification Method**: - -- Used grep to verify links in dist/ HTML files -- Confirmed all internal navigation links functional -- Confirmed consistent Header/Footer across all pages - -Status: ✅ Complete -Completed: 2025-10-20 03:24:30 - ---- - -### Task 7: Final Validation Gates and Content Verification - -Started: 2025-10-20 03:25:00 -File: N/A (validation & verification) - -**Validation Gates**: - -- ✅ pnpm lint: Passed - all files formatted correctly -- ✅ pnpm typecheck: 0 errors, 0 warnings, 0 hints (14 files) -- ✅ pnpm build: Completed successfully - 4 pages built - -**Content Verification**: - -- ✅ No marc@ emails found (critical fix verified) -- ✅ support@trakrf.id present in privacy-policy and tos -- ✅ No shipfa.st references found (all cleaned) -- ✅ "United States of America" governing law in TOS -- ✅ No "France" references in TOS (changed to USA) -- ✅ No console.log or debugger statements in source code - -**Build Output Verification**: - -- ✅ dist/index.html (homepage) -- ✅ dist/blog/index.html (blog placeholder) -- ✅ dist/privacy-policy/index.html (privacy policy) -- ✅ dist/tos/index.html (terms of service) - -**Critical Fixes Confirmed**: - -1. Privacy Policy: marc@trakrf.id → support@trakrf.id ✅ -2. TOS: marc@shipfa.st → support@trakrf.id ✅ -3. TOS: France → United States of America ✅ -4. Dates updated to 2025-10-20 ✅ - -Status: ✅ Complete -Completed: 2025-10-20 03:25:50 - ---- - -## Summary - -Total tasks: 7 -Completed: 7 -Failed: 0 -Duration: ~6 minutes - -**Implementation Results**: - -1. ✅ Created BaseLayout component for DRY page structure -2. ✅ Created blog placeholder page at /blog -3. ✅ Created Privacy Policy page with critical email fix -4. ✅ Created Terms of Service page with critical fixes (email + governing law) -5. ✅ Added blog link to Footer navigation -6. ✅ Verified multi-page navigation across all pages -7. ✅ Passed all validation gates and content verification - -**Files Created**: - -- src/layouts/BaseLayout.astro -- src/pages/blog/index.astro -- src/pages/privacy-policy.astro -- src/pages/tos.astro - -**Files Modified**: - -- src/components/Footer.astro (added blog link) - -**Critical Fixes Applied**: - -1. Privacy Policy: marc@trakrf.id → support@trakrf.id ✅ -2. TOS: marc@shipfa.st → support@trakrf.id ✅ -3. TOS: France → United States of America ✅ -4. Both legal pages: Dates updated to 2025-10-20 ✅ - -**Validation Results**: - -- Lint: ✅ Passed -- Typecheck: ✅ 0 errors -- Build: ✅ 4 pages generated -- Content: ✅ All critical fixes verified -- Navigation: ✅ All links functional - -**Phase 3 Goals Achieved**: - -✅ Blog placeholder page functional at /blog -✅ Privacy Policy page production-ready with cleaned content -✅ Terms of Service page production-ready with cleaned content -✅ All navigation links working (blog, privacy-policy, tos) -✅ Site structure 100% complete -✅ Zero structural debt - trakrf-web migration complete - -Ready for /check: YES - -**Next Steps**: Run /check for pre-release validation diff --git a/spec/content-migration-phase3/plan.md b/spec/content-migration-phase3/plan.md deleted file mode 100644 index e2eb11f..0000000 --- a/spec/content-migration-phase3/plan.md +++ /dev/null @@ -1,504 +0,0 @@ -# Implementation Plan: TrakRF-Web Content Migration - Phase 3 - -Generated: 2025-10-20 -Specification: spec.md - -## Understanding - -Phase 3 completes the TrakRF marketing site structural migration by adding: - -1. **Blog placeholder page** - "Coming Soon" page at `/blog` (not migrating template sample posts) -2. **Privacy Policy page** - Full legal text with critical email cleanup (`marc@trakrf.id` → `support@trakrf.id`) -3. **Terms of Service page** - Full legal text with critical email cleanup (`marc@shipfa.st` → `support@trakrf.id`) and governing law change (France → USA) - -This achieves complete closure on the trakrf-web migration by extracting all remaining structural value (routes, navigation, page architecture) without migrating irrelevant template content. After this phase, there's zero reason to revisit the trakrf-web codebase. - -**Philosophy**: "Squeeze all the juice" - extract structure, not content. - -## Relevant Files - -**Reference Patterns** (existing code to follow): - -- `src/pages/index.astro` (lines 1-69) - Page structure with Header/Footer, SEO metadata pattern -- `src/components/Header.astro` - Header component to import -- `src/components/Footer.astro` (lines 34-44) - LINKS section where blog link should be added -- `src/styles/global.css` - Global styles already available - -**Files to Create**: - -- `src/layouts/BaseLayout.astro` - Reusable page layout with Header, Footer, SEO (DRY principle) -- `src/pages/blog/index.astro` - Blog placeholder "Coming Soon" page -- `src/pages/privacy-policy.astro` - Privacy policy with cleaned content -- `src/pages/tos.astro` - Terms of service with cleaned content - -**Files to Modify**: - -- `src/components/Footer.astro` (lines 34-44) - Add blog link to LINKS section - -**Source Files** (reference only, not modified): - -- `/home/mike/trakrf-web/app/privacy-policy/page.tsx` (lines 60-104) - Privacy policy content -- `/home/mike/trakrf-web/app/tos/page.tsx` (lines 60-92) - TOS content - -## Architecture Impact - -- **Subsystems affected**: Pages/Routing (static pages only) -- **New dependencies**: None -- **Breaking changes**: None - -## Task Breakdown - -### Task 1: Create BaseLayout Component - -**File**: `src/layouts/BaseLayout.astro` -**Action**: CREATE -**Pattern**: Reference `src/pages/index.astro` lines 1-39 for HTML structure and SEO metadata - -**Implementation**: - -```astro ---- -import '../styles/global.css'; -import Header from '../components/Header.astro'; -import Footer from '../components/Footer.astro'; - -interface Props { - title: string; - description: string; - ogImage?: string; -} - -const { title, description, ogImage = '/images/opengraph-image.png' } = Astro.props; ---- - - - - - - - {title} - - - - - - - - - - - - - - - - - - -
-
- -
-