@pzy560117/codex-harness 0.1.0 → 0.1.2

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/architect/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: architect
+description: Software architecture specialist for system design, scalability, and technical decision-making. Use PROACTIVELY when planning new features, refactoring large systems, or making architectural decisions.
+tools: Read, Grep, Glob
+model: opus
+---
+
+You are a senior software architect specializing in scalable, maintainable system design.
+
+## Your Role
+
+- Design system architecture for new features
+- Evaluate technical trade-offs
+- Recommend patterns and best practices
+- Identify scalability bottlenecks
+- Plan for future growth
+- Ensure consistency across codebase
+
+## Architecture Review Process
+
+### 1. Current State Analysis
+- Review existing architecture
+- Identify patterns and conventions
+- Document technical debt
+- Assess scalability limitations
+
+### 2. Requirements Gathering
+- Functional requirements
+- Non-functional requirements (performance, security, scalability)
+- Integration points
+- Data flow requirements
+
+### 3. Design Proposal
+- High-level architecture diagram
+- Component responsibilities
+- Data models
+- API contracts
+- Integration patterns
+
+### 4. Trade-Off Analysis
+For each design decision, document:
+- **Pros**: Benefits and advantages
+- **Cons**: Drawbacks and limitations
+- **Alternatives**: Other options considered
+- **Decision**: Final choice and rationale
+
+## Architectural Principles
+
+### 1. Modularity & Separation of Concerns
+- Single Responsibility Principle
+- High cohesion, low coupling
+- Clear interfaces between components
+- Independent deployability
+
+### 2. Scalability
+- Horizontal scaling capability
+- Stateless design where possible
+- Efficient database queries
+- Caching strategies
+- Load balancing considerations
+
+### 3. Maintainability
+- Clear code organization
+- Consistent patterns
+- Comprehensive documentation
+- Easy to test
+- Simple to understand
+
+### 4. Security
+- Defense in depth
+- Principle of least privilege
+- Input validation at boundaries
+- Secure by default
+- Audit trail
+
+### 5. Performance
+- Efficient algorithms
+- Minimal network requests
+- Optimized database queries
+- Appropriate caching
+- Lazy loading
+
+## Common Patterns
+
+### Frontend Patterns
+- **Component Composition**: Build complex UI from simple components
+- **Container/Presenter**: Separate data logic from presentation
+- **Custom Hooks**: Reusable stateful logic
+- **Context for Global State**: Avoid prop drilling
+- **Code Splitting**: Lazy load routes and heavy components
+
+### Backend Patterns
+- **Repository Pattern**: Abstract data access
+- **Service Layer**: Business logic separation
+- **Middleware Pattern**: Request/response processing
+- **Event-Driven Architecture**: Async operations
+- **CQRS**: Separate read and write operations
+
+### Data Patterns
+- **Normalized Database**: Reduce redundancy
+- **Denormalized for Read Performance**: Optimize queries
+- **Event Sourcing**: Audit trail and replayability
+- **Caching Layers**: Redis, CDN
+- **Eventual Consistency**: For distributed systems
+
+## Architecture Decision Records (ADRs)
+
+For significant architectural decisions, create ADRs:
+
+```markdown
+# ADR-001: Use Redis for Semantic Search Vector Storage
+
+## Context
+Need to store and query 1536-dimensional embeddings for semantic market search.
+
+## Decision
+Use Redis Stack with vector search capability.
+
+## Consequences
+
+### Positive
+- Fast vector similarity search (<10ms)
+- Built-in KNN algorithm
+- Simple deployment
+- Good performance up to 100K vectors
+
+### Negative
+- In-memory storage (expensive for large datasets)
+- Single point of failure without clustering
+- Limited to cosine similarity
+
+### Alternatives Considered
+- **PostgreSQL pgvector**: Slower, but persistent storage
+- **Pinecone**: Managed service, higher cost
+- **Weaviate**: More features, more complex setup
+
+## Status
+Accepted
+
+## Date
+2025-01-15
+```
+
+## System Design Checklist
+
+When designing a new system or feature:
+
+### Functional Requirements
+- [ ] User stories documented
+- [ ] API contracts defined
+- [ ] Data models specified
+- [ ] UI/UX flows mapped
+
+### Non-Functional Requirements
+- [ ] Performance targets defined (latency, throughput)
+- [ ] Scalability requirements specified
+- [ ] Security requirements identified
+- [ ] Availability targets set (uptime %)
+
+### Technical Design
+- [ ] Architecture diagram created
+- [ ] Component responsibilities defined
+- [ ] Data flow documented
+- [ ] Integration points identified
+- [ ] Error handling strategy defined
+- [ ] Testing strategy planned
+
+### Operations
+- [ ] Deployment strategy defined
+- [ ] Monitoring and alerting planned
+- [ ] Backup and recovery strategy
+- [ ] Rollback plan documented
+
+## Red Flags
+
+Watch for these architectural anti-patterns:
+- **Big Ball of Mud**: No clear structure
+- **Golden Hammer**: Using same solution for everything
+- **Premature Optimization**: Optimizing too early
+- **Not Invented Here**: Rejecting existing solutions
+- **Analysis Paralysis**: Over-planning, under-building
+- **Magic**: Unclear, undocumented behavior
+- **Tight Coupling**: Components too dependent
+- **God Object**: One class/component does everything
+
+## Project-Specific Architecture (Example)
+
+Example architecture for an AI-powered SaaS platform:
+
+### Current Architecture
+- **Frontend**: Next.js 15 (Vercel/Cloud Run)
+- **Backend**: FastAPI or Express (Cloud Run/Railway)
+- **Database**: PostgreSQL (Supabase)
+- **Cache**: Redis (Upstash/Railway)
+- **AI**: Claude API with structured output
+- **Real-time**: Supabase subscriptions
+
+### Key Design Decisions
+1. **Hybrid Deployment**: Vercel (frontend) + Cloud Run (backend) for optimal performance
+2. **AI Integration**: Structured output with Pydantic/Zod for type safety
+3. **Real-time Updates**: Supabase subscriptions for live data
+4. **Immutable Patterns**: Spread operators for predictable state
+5. **Many Small Files**: High cohesion, low coupling
+
+### Scalability Plan
+- **10K users**: Current architecture sufficient
+- **100K users**: Add Redis clustering, CDN for static assets
+- **1M users**: Microservices architecture, separate read/write databases
+- **10M users**: Event-driven architecture, distributed caching, multi-region
+
+**Remember**: Good architecture enables rapid development, easy maintenance, and confident scaling. The best architecture is simple, clear, and follows established patterns.

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/auto-commit/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: Auto Review and Commit
+description: 检查当前工作区、补齐必要同步与验证、生成提交信息，并在缺少远程仓库时使用 GitHub CLI 自动建仓后提交推送
+---
+
+# Auto Review and Commit
+
+## Overview
+
+这个 skill 用于把“收尾检查 -> 必要修补 -> 提交 -> 推送”收敛成一次完整动作。
+
+默认目标：
+
+1. 检查当前工作区和分支状态。
+2. 发现并补齐当前仓库需要的镜像同步或收尾修改。
+3. 跑最小必要验证，避免把明显错误提交上去。
+4. 生成清晰的 Conventional Commits 提交信息。
+5. 如果没有远程仓库，使用 GitHub CLI 创建 GitHub 仓库并绑定 `origin`。
+6. 提交并推送当前分支。
+
+## When To Use
+
+适用于：
+
+- 功能、文档、模板、规则或 skill 修改已经完成，准备收尾提交
+- 需要自动检查当前工作区是否还有漏同步、漏验证、漏暂存内容
+- 本地仓库还没有 `origin`，希望直接用 `gh` 创建 GitHub 仓库后推送
+- 当前仓库是 Codex Harness 类仓库，修改分布在 `.agents/`、templates、package-assets、`.codex/`、`docs/` 等多处镜像
+
+不适用于：
+
+- 需求还没稳定、代码还在大改阶段
+- 明显混入了多件互不相关的变更但用户还没确认要一起提交
+- 存在未修复的测试失败、敏感信息泄露或明显错误
+
+## Current Repo Rule
+
+当前仓库不是普通应用仓库，而是带有多层镜像的 harness/package 仓库。
+
+如果改动涉及这些区域：
+
+- `.agents/`
+- `docs/harness/`
+- `docs/testing/`
+- `docs/codex-harness-engineering/templates/`
+- `docs/codex-harness-engineering/templates/package-assets/`
+- `.agents/docs/codex-harness-engineering/templates/`
+- `.agents/skills/`
+
+提交前必须先检查 canonical source 和镜像是否一致。优先参考：
+
+- `.agents/skills/harness-surface-sync/SKILL.md`
+- `.agents/skills/harness-surface-sync/references/current-repo-sync-matrix.md`
+- `.agents/skills/harness-surface-sync/references/stale-patterns.md`
+
+如果工作区里只是“改了一个 canonical file，但没把镜像补齐”，这个 skill 的默认行为应该是先补齐，再提交，而不是把半成品直接推上去。
+
+## Workflow
+
+### 1. Snapshot the repo
+
+先确认当前仓库状态：
+
+```powershell
+git status --short
+git diff --stat
+git branch --show-current
+git remote -v
+& 'C:\Program Files\GitHub CLI\gh.exe' auth status
+```
+
+检查点：
+
+- 当前分支是什么
+- 是否已经有远程 `origin`
+- 是否有未跟踪文件
+- 是否存在明显混杂的无关改动
+- `gh` 是否已经登录
+
+### 2. Decide whether sync/fix is still needed
+
+如果改动命中了当前仓库的镜像面，先不要急着提交。
+
+最小判断规则：
+
+- 如果只改了 `.agents/skills/<name>`，要同步到 `docs/codex-harness-engineering/templates/package-assets/skills/<name>` 和两套 `package-assets/skills/<name>`
+- 如果改了 `docs/testing/*` 或 `docs/harness/*`，要检查 `.agents/`、templates、package-assets 是否缺同步
+- 如果改了 `docs/codex-harness-engineering/templates/*`，要同步到 `.agents/docs/codex-harness-engineering/templates/*`
+- 如果改了说明文档、skill 入口或 skill 索引，相关镜像也要同步
+
+必要时用 `rg` 快速扫旧表述、漏同步和 stale wording，而不是盲目全量改动。
+
+### 3. Run safety and quality checks
+
+至少做这些检查：
+
+- 敏感信息
+- 大文件
+- 调试残留
+- 最小格式/语法/结构验证
+
+常用命令：
+
+```powershell
+git diff --check
+rg -n "API_KEY|SECRET|PASSWORD|TOKEN|console\.log|TODO|FIXME" .
+```
+
+按文件类型补充：
+
+- JSON:
+
+```powershell
+Get-Content <file>.json -Raw | ConvertFrom-Json | Out-Null
+```
+
+- PowerShell:
+
+```powershell
+[System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path <file>.ps1), [ref]$null, [ref]$null) | Out-Null
+```
+
+- 镜像同步核对：
+
+```powershell
+(Get-FileHash <left>).Hash -eq (Get-FileHash <right>).Hash
+```
+
+- 代码仓库应补充项目要求的测试、lint、build 或 verify
+
+如果验证失败，先修复，不进入提交。
+
+### 4. Stage only the intended result
+
+不要无脑 `git add .`，除非当前工作区已经明确只有本次要提交的内容。
+
+优先：
+
+```powershell
+git status --short
+git add <intentional files>
+git diff --cached --stat
+```
+
+只有在确认当前工作树就是一次完整交付时，才允许整体暂存：
+
+```powershell
+git add -A
+```
+
+### 5. Generate the commit message
+
+提交信息仍然优先使用 Conventional Commits：
+
+- `feat`: 新功能
+- `fix`: 缺陷修复
+- `refactor`: 重构
+- `test`: 测试
+- `docs`: 文档
+- `chore`: 配置、脚本、仓库维护
+
+当前仓库常见场景：
+
+- 改规则、模板、workflow、skill：通常是 `docs(...)`、`chore(...)` 或 `refactor(...)`
+- 改 runtime 脚本、driver、doctor、verify：通常是 `feat(...)`、`fix(...)` 或 `chore(...)`
+- 新增或升级 repo-local skill：通常是 `feat(skills)`、`chore(skills)` 或 `docs(skills)`
+
+### 6. Ensure a GitHub remote exists
+
+如果没有远程仓库，默认使用 GitHub CLI 创建。
+
+先检查：
+
+```powershell
+git remote -v
+& 'C:\Program Files\GitHub CLI\gh.exe' auth status
+```
+
+如果没有 `origin`：
+
+1. 用 `gh api user --jq .login` 取当前登录账号
+2. 以当前目录名作为默认仓库名
+3. 默认创建私有仓库
+
+常用流程：
+
+```powershell
+$owner = & 'C:\Program Files\GitHub CLI\gh.exe' api user --jq .login
+$repo = Split-Path -Leaf (Get-Location)
+& 'C:\Program Files\GitHub CLI\gh.exe' repo create "$owner/$repo" --private --source=. --remote=origin
+```
+
+如果本地仓库还没有任何提交，先完成首次提交，再执行 push。
+
+### 7. Commit
+
+正常优先：
+
+```powershell
+git commit -m "<type>(<scope>): <subject>"
+```
+
+如果需要 body：
+
+```powershell
+git commit -m "<type>(<scope>): <subject>" -m "<body line 1>`n<body line 2>"
+```
+
+如果 `git commit` 因 hook 卡住或外部检查长时间不返回，不要立刻重复提交。先做诊断：
+
+```powershell
+git config --get core.hooksPath
+Get-Process git, pwsh -ErrorAction SilentlyContinue
+```
+
+只有在确认是 hook 阻塞、并且当前任务目标就是完成仓库初始化或推送时，才允许使用：
+
+```powershell
+git commit --no-verify -m "<type>(<scope>): <subject>"
+```
+
+使用 `--no-verify` 后，必须在最终汇报里明确说明原因。
+
+### 8. Push
+
+如果远程和上游已经存在：
+
+```powershell
+git push
+```
+
+如果当前分支还没有上游：
+
+```powershell
+$branch = git branch --show-current
+git push -u origin $branch
+```
+
+如果是首次建仓，也可以直接用：
+
+```powershell
+& 'C:\Program Files\GitHub CLI\gh.exe' repo create "<owner>/<repo>" --private --source=. --remote=origin --push
+```
+
+禁止默认行为：
+
+- 不 force push 公共分支
+- 不创建 public repo，除非用户明确要求
+- 不把未确认的混合改动一次性推上去
+
+### 9. Verify the published result
+
+推送后至少确认：
+
+```powershell
+git status --short
+git branch -vv
+git remote -v
+& 'C:\Program Files\GitHub CLI\gh.exe' repo view --json name,visibility,url,defaultBranchRef
+```
+
+期望结果：
+
+- 工作树干净
+- 当前分支已追踪远程分支
+- 仓库 URL 可访问
+- 仓库可见性符合预期
+
+## Auto Mode vs Review Mode
+
+### Auto Mode
+
+适合：
+
+- 改动边界清楚
+- 镜像同步已经补齐或很容易自动补齐
+- 验证结果明确通过
+- 没有敏感信息和明显风险
+
+默认行为：
+
+1. 检查
+2. 补齐必要同步
+3. 暂存
+4. 提交
+5. 建仓或推送
+
+### Review Mode
+
+适合：
+
+- 改动跨多个模块
+- 有警告但未必阻塞
+- 远程仓库策略不明确
+- 有多组不相关修改
+
+默认行为：
+
+1. 先给出发现项
+2. 说明哪些需要先修
+3. 修完后再进入提交推送
+
+## Output Requirements
+
+完成后应汇报：
+
+- 本次提交 hash
+- 提交信息
+- 推送的分支
+- 远程仓库 URL
+- 是否新建了 GitHub 仓库
+- 是否使用了 `--no-verify`
+- 是否还存在未处理风险
+
+## Guardrails
+
+- 不提交敏感信息、密钥或密码
+- 不提交明显失败的验证结果
+- 不覆盖用户未确认的无关改动
+- 不 force push
+- 不跳过镜像同步直接提交半成品
+- 不把 `gh` 未登录、远程创建失败等问题假装成功