Open
Conversation
Add standardized schema for capturing project context that workers need to understand any project. Includes templates for core files (overview, architecture, domain) and recommended files (decisions, stakeholders). JSON schema enables validation. Example context created for distributed-tracking project demonstrates the schema in practice. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add new worker to discover, maintain, and audit project context: - worker.yaml with CodeWorker definition - discover skill: extract context from repos or conversation - audit skill: check freshness and completeness - update skill: update specific context files Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add registry.yaml documenting context needs for all worker types - Document CodeWorker, ContentWorker, SocialWorker, ResearchWorker, OpsWorker, and AssistantWorker context requirements - Support individual worker overrides (architect, security-scanner, context-manager) - Add README.md explaining how to declare needs for new workers - Define schema for type defaults, individual overrides, and external context references Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add new Step 5 to /prd command that offers project context population after PRD creation. Users can choose from: - Manual: Create empty templates for user to fill - Automatic: Extract context from target repo docs - Conversational: Interview user about the project - Skip: Proceed without context (with warning) This enables workers to understand projects deeply, not just track tasks. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add new Section 5 "Context Needs" to Interactive Setup - Add context_needs field to worker.yaml template - Add "Update Context Needs Registry" section for worker-specific overrides - Links to knowledge/context-needs/ for reference Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add detailed repo analysis implementation to the discover skill: - Step-by-step process for locating and analyzing repos - Source extraction tables for README, package.json, configs - Mapping rules from sources to context file sections - Draft generation and user review workflow - Incremental update mode (--update flag) documentation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
After PRD completion, /run-project now triggers context-manager audit skill to check project context for staleness. This ensures context stays current as the codebase evolves during PRD execution. - Adds step 8c to project completion flow - Spawns context-manager audit skill after aggregating learnings - Logs audit results to progress.txt - Suggests context discovery if no context exists Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add comprehensive interview flow to context-manager discover skill: - 9 batched questions grouped by section (Overview, Architecture, Domain) - Support for pasting existing docs with extraction rules by doc type - Hybrid mode allowing automatic analysis mid-interview - Source attribution in frontmatter tracking interview details Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Create learnings.md template with sections: Patterns, Gotchas, Tips, Open Questions - Add learn skill to context-manager worker for appending insights - Define learning entry format: ### [Date] [Worker] [Task]: Title - Support category tagging for filtering: pattern, gotcha, tip, question, etc. - Add learnings_added metric to worker reporting Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
All 9 user stories verified complete: - US-001: Project context schema with templates - US-002: Context-manager worker with 4 skills - US-003: Worker context needs registry - US-004: Context discovery in /prd command - US-005: Context needs capture in /newworker - US-006: Repo analysis discovery skill - US-007: Staleness detection and post-PRD audit trigger - US-008: Conversational discovery mode - US-009: Learnings accumulation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Two issues fixed: 1. Completion detection now recognizes both formats: - `passes: true` (old format) - `status: "completed"` (new format used by Claude sessions) The orchestrator was infinitely looping because it only checked for `passes == true` but tasks were marked with `status: "completed"`. 2. Auto-create PR when PRD completes: - Push branch to origin - Use gh CLI to create PR with summary from PRD - Include task list in PR body - Fallback message if gh not available Both PowerShell and bash scripts updated. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When creating PRs after PRD completion, the orchestrator now: 1. Checks for 'myfork' or 'fork' remotes 2. If found, pushes to the fork remote instead of origin 3. Extracts upstream repo URL from origin for PR target 4. Uses --repo flag with gh pr create to target upstream This allows fork-based workflows where origin points to upstream and myfork/fork points to the user's fork. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
New testing infrastructure for HQ PRs: - .claude/scripts/validate-pr.ps1: Automated validation script - Script syntax checking (PowerShell, Bash) - YAML/JSON syntax validation - Worker registry consistency - PRD file existence verification - Command file structure checks - knowledge/testing/pr-validation.md: Testing strategy docs - Automated check catalog - Functional test guidelines - Future CI integration notes Usage: .\validate-pr.ps1 -Project project-context-manager Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
New command that builds verified project understanding through: 1. Automatic repo analysis (like discover) 2. Present interpretation to user 3. Probing questions per section (purpose, architecture, domain, ops) 4. User confirms, corrects, or expands 5. Write verified context files with confidence levels Key differences from /run context-manager discover: - Interactive interview process - Human verification of AI understanding - Captures "why" not just "what" - Saves interview log for future reference - Higher confidence context files Usage: /understand-project indigo-nx --repo C:/repos/indigo-nx This is foundational for agentic success - agents that misunderstand projects produce poor results. Context alignment matters. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add /understand-project to CLAUDE.md Projects section - Add learning about interview-based discovery catching misunderstandings - Expand schema.md with discovery methods documentation: - Quick discovery via /run context-manager discover - Deep discovery via /understand-project - When to use which approach - Context in external repos documentation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add prd.json template to Step 4 alongside README.md - Add target_repo question to discovery interview - Update completion message to show both files - Add rule emphasizing both files must be generated Execution commands (/pure-ralph, /run-project, /execute-task) require prd.json but /prd was only generating README.md. This fixes the gap. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
prd.json is a functional document that mirrors README.md content. No need to show the template to users. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Research findings for hq-installer project: - Essential deps: Node.js 18+, Claude CLI (only 2 required) - Optional: Git, gh CLI, qmd, pnpm (with graceful degradation) - Documented installer strategy with 3-tier dependency approach - Confirmed authentication flow (Claude OAuth) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Create Windows installer with: - NSIS script with MUI2 branded UI and progress indicators - Node.js detection and silent install if missing - Claude CLI detection and npm install if missing - User-selectable install location (default: AppData/Local) - Start Menu and Desktop shortcuts - Comprehensive code-signing documentation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Create complete macOS installer package with: - build-pkg.sh script using pkgbuild/productbuild - Branded HTML UI (welcome, readme, license, conclusion pages) - preinstall script for Node.js/Claude CLI detection - postinstall script for auto-installation of dependencies - PATH configuration via ~/.zshrc and /etc/paths.d - Code signing and notarization documentation The installer detects missing Node.js 18+ and Claude CLI, downloads and installs them automatically, and configures the user's shell PATH for immediate use. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Windows NSIS: Add ClaudeAuthPage custom page after installation - Uses 'claude setup-token' command for browser OAuth - Allows skip and retry with clear messaging - Checks authentication status before prompting - macOS pkg: Update postinstall and conclusion page - Updated conclusion.html with OAuth instructions - Added authenticate-claude.sh helper script to ~/my-hq/ - Instructions for 'claude setup-token' command - Shared: Add cross-platform OAuth helper scripts - installer/shared/scripts/claude-oauth.ps1 (Windows) - installer/shared/scripts/claude-oauth.sh (macOS/Linux) Both platforms support: - Browser OAuth via 'claude setup-token' command - Skip authentication for later manual setup - Clear messaging about /login for manual auth Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Created installer/template/ with starter files: - agents.md (user profile template) - CLAUDE.md (Claude configuration) - USER-GUIDE.md (documentation) - setup.md command (setup wizard) - Directory structure for workers, projects, workspace, knowledge - Updated Windows NSIS installer: - Bundled or downloaded template from GitHub releases - Added SEC06 for npm install if package.json exists - Desktop shortcut with welcome message - Fallback to minimal structure if download fails - Updated macOS installer: - Updated build-pkg.sh with template download option - postinstall creates ~/Desktop/my-hq.app launcher bundle - run_npm_install function for template dependencies - No Git required - uses HTTPS download Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Create cross-platform terminal-based setup wizard - Windows: setup-wizard.ps1 (PowerShell) - macOS: setup-wizard.sh (Bash) - Wizard collects user profile (name, role, goals, preferences) - Writes configured agents.md with user information - Shows Getting Started guide with key commands - Supports skip at any point for manual configuration later Windows integration: - NSIS finish page launches wizard via PowerShell - Start Menu shortcut added for re-running wizard macOS integration: - Wizard auto-launches after installation completes - Desktop app "my-hq Setup Wizard.app" for re-running Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add cross-platform update checking infrastructure: - check-updates.ps1 for Windows: PowerShell script that queries GitHub releases API, compares versions, downloads and installs updates - check-updates.sh for macOS: Bash script with same functionality - Windows NSIS installer: Includes update checker, Start Menu shortcut, saves .hq-version file for tracking - macOS postinstall: Includes update checker, creates desktop .app launcher, saves .hq-version file Features: - Checks GitHub releases API for latest version - Compares semantic versions (major.minor.patch) - Shows release notes when update available - Downloads installer with user consent - Rate-limited to once-per-day checks - Preserves user data during updates Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The test now verifies the COMPLETE installation experience: - Confirms clean environment (no pre-installed Node.js, npm, Claude) - Runs installer - Verifies Node.js is installed and working - Verifies npm is installed and working - Verifies Claude CLI is installed and working - Fails with clear errors if ANY component is missing No more partial passes. The installer must fully work. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Replace package validation with real macOS VM testing - Use sickcodes/docker-osx:auto with SSH access - Test flow: boot VM, copy pkg via SCP, run installer, verify - Verify Node.js, npm, Claude CLI, and my-hq files installation - Includes fallback to package validation if Docker-OSX fails - Both Windows and macOS now have true clean room tests Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Try sonoma -> ventura -> monterey -> latest - Store selected image in GITHUB_ENV for docker run - Increase pull timeout to 45 minutes for large images Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Docker-OSX requires manual macOS setup through VNC and is not suitable for headless CI testing. Instead, use macos-latest runner directly: - Pre-install check documents existing environment - Run actual pkg installer with sudo - Verify all components: my-hq files, Node.js, npm, Claude CLI - Clear pass/fail output Windows remains a true clean room test (Docker container with no software). macOS verifies the installer works on a real macOS system. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Scripts edited on Windows have CRLF line endings which cause bash to fail. Add explicit line ending conversion step before building the pkg. Also ensure scripts have executable permissions. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Avoid sourcing .zshrc (can fail in CI) - Explicitly set PATH in each verification step - Ensure all steps have consistent PATH Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The macOS pkg installer now also installs Claude CLI via npm: - Finds npm in common locations (/opt/homebrew, /usr/local, /usr) - Runs npm install -g @anthropic-ai/claude-code - Handles running as root by using sudo -u for target user - Logs all operations to /tmp/my-hq-installer.log This brings parity with the Windows installer which also downloads and installs Node.js + Claude CLI. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Show contents of /tmp/my-hq-installer.log after running the pkg to diagnose why Claude CLI isn't being installed. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The pkg installer runs scripts with minimal PATH, so npm couldn't find node. - Set PATH to include /opt/homebrew/bin, /usr/local/bin before running npm - Pass PATH through sudo -u when running as target user - Log the PATH for debugging Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Configure installer/docs as output directory for landing page - Enable GitHub integration for automatic deployments - Set cache headers and clean URLs - Part of e2e-cloud-testing project US-001 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Document preview deployment workflow via CLI - Include URL patterns for discovery - Document environment variables (TEST_MODE) - Add troubleshooting section for common issues - Part of e2e-cloud-testing project US-001 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Vercel project 'hq-installer' configured and deployed - Production URL: https://hq-installer.vercel.app - TEST_MODE environment variable set for preview - SSO protection disabled for E2E test access - Documentation created at knowledge/testing/vercel-preview-deployments.md - Noted limitations for follow-up (GitHub App, expiration, MCP) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Create .github/workflows/e2e.yml that deploys to Vercel and runs E2E tests - Workflow triggers on push (except main) and pull requests - Waits for Vercel preview deployment to be ready before testing - Uploads test artifacts (JSON, HTML report, failure screenshots/videos) - Posts test results as PR comment with pass/fail summary Playwright test suite for hq-installer landing page: - Page load and title verification - Logo, tagline, and OS detection - Download buttons and platform links - FAQ accordion expand/collapse - Tab switching for installation instructions - Responsive design and accessibility checks All 21 tests pass against production (https://hq-installer.vercel.app). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implementation includes: - .github/workflows/e2e.yml with Vercel preview deployment - Wait for deployment ready (up to 5 min timeout) - Playwright test execution with JSON/HTML reporters - Artifact upload on failure - PR comment with test results summary Playwright test suite (21 tests passing locally): - Landing page load and display - OS detection - Download buttons - FAQ accordion - Tab switching - Responsive design - Accessibility Requires VERCEL_TOKEN GitHub secret for workflow execution. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add @browserbasehq/sdk for cloud browser execution
- Create custom Playwright fixture for Browserbase CDP connection
- Update playwright.config.ts with auto-detection and parallel workers
- Update GitHub Actions workflow with Browserbase secrets support
- Add fallback to local Playwright when Browserbase unavailable
- Create knowledge/testing/browserbase-integration.md documentation
- Add npm scripts: test:browserbase, test:local
Session recordings available at browserbase.com/sessions/{id}
SETUP REQUIRED: Add BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID
secrets to GitHub repo.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Created comprehensive Playwright testing templates: - nextjs-webapp.md: Next.js/React web apps with forms, navigation, interactive components - cli-browser-oauth.md: CLI tools with browser-based OAuth flows - api-endpoints.md: REST API testing with CRUD, auth, schema validation - README.md: Quick reference for when to use each template Each template includes setup, common patterns, assertions, and cleanup sections. Templates aligned with existing hq-installer test patterns. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The markdown bold syntax (**text**) at the start of lines in JavaScript template strings was being misinterpreted as YAML alias references (*Execution). Fixed by building the PR comment body using array join instead of multiline template literal. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Always install Playwright browsers (simpler, more reliable)
- Use env vars to access secrets in shell script instead of direct
${{ secrets.* }} interpolation which can cause parsing issues
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Validated the full E2E testing infrastructure: - 21 tests pass locally in 4s against production URL - Tests cover all acceptance criteria (OS detection, downloads, FAQ accordion, tabs, responsive, accessibility) - GitHub Actions workflow fixed and validated - Detailed validation notes in projects/e2e-cloud-testing/validation-notes.md Setup required: Add VERCEL_TOKEN to GitHub secrets for automated preview deployments. Browserbase secrets are optional. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Created comprehensive knowledge/testing/e2e-cloud.md documenting: - Complete CI workflow (deploy → wait → test → report) - How to view results via GH Actions, artifacts, PR comments - Interpreting failures with jq commands and traces - Browserbase session recordings - gh CLI quick reference for all operations - Writing tests with template links - Troubleshooting guide Linked from CLAUDE.md Testing Requirements section. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Added e2e-testing skill to frontend-dev and backend-dev workers: - Created skills/e2e-testing.md with write/run/debug/fix actions - Updated worker.yaml context to include testing templates - Added e2e_testing to MCP tools list Note: fullstack-dev worker does not exist in codebase. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Create knowledge/hq-core/prd-schema.md with comprehensive PRD schema docs - Add e2eTests[] as REQUIRED field per user story - Create .claude/scripts/validate-prd.ps1 for PRD validation - Update /prd command with Batch 4 E2E testing questions - Validation tested: PRDs without e2eTests fail, with e2eTests pass Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Updates pure-ralph-base.md to require CI E2E tests pass before marking tasks complete: - Added "CI E2E Verification" section with full workflow documentation - Step-by-step commands for triggering, waiting, and verifying CI tests - 15-minute timeout handling with clear BLOCKED status - Failure handling with artifact download commands - Emergency skip documentation with audit requirements - Updated "Your Job" steps to include PUSH and VERIFY CI - Added learned patterns for CI verification best practices This ensures agents verify their code in the actual CI environment, not just locally, preventing environment-specific issues from shipping. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Configure branch protection on johnsonfamily1234/hq-starter-kit - Require 'Run E2E Tests' status check (strict mode) - Add 'Branch Protection & Quality Gates' section to e2e-cloud.md - Document emergency override procedures for admins - Include repo configuration commands for new repos - Verified: PR #2 shows UNSTABLE merge state with failing E2E Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Create scripts/process-results.js that transforms Playwright JSON into
clean agent-parseable format with failures, screenshots, traces, artifacts
- Update e2e.yml workflow to generate agent-results.json and include in artifacts
- Enhance PR comment template with expandable failure details, artifact links,
and gh CLI commands for downloading/parsing results
- Add comprehensive jq commands to e2e-cloud.md for parsing test results
- Document agent-results.json schema and one-liner for quick failure checks
- Add npm scripts: test:agent (run tests + process), process-results
Agent-friendly output includes:
- summary: {total, passed, failed, skipped, flaky, duration}
- status: "passed" | "failed" (quick check)
- failures: [{test, file, line, error, screenshot, trace}]
- artifacts: {screenshots, traces, videos}
- meta: {timestamp, baseUrl, executionMode}
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add show-test-coverage.ps1 script for displaying test coverage - Add collect-test-metrics.ps1 for gathering metrics from agent-results.json - Update metrics.md with --tests flag and test coverage documentation - Create workspace/metrics/test-coverage.jsonl for storing test data - Support trend tracking (last 5 runs per project) - Alert when coverage drops below 80% threshold Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Every code change in HQ-managed projects is automatically E2E tested in the cloud before merge, with agents both writing and running tests as part of their standard workflow
Completed Tasks
Created by Pure Ralph