Skip to content

Commit 3b8f0a6

Browse files
amondnetamondnet
committed
chore: initialize .please/ workspace and update claude code settings
- Add .please/ workspace scaffold with config, knowledge docs, product specs, and active tracks (improve-test-coverage) - Update .claude/settings.json: enable plugins (gh-please, please, review, github, standards, dev-tools, vue, antfu, vitest, gatekeeper, claude-code-setup, cloudflare), set env vars, add extra marketplaces - Add .please/state/ to .gitignore to exclude runtime state from version control
1 parent 436e9eb commit 3b8f0a6

15 files changed

Lines changed: 407 additions & 10 deletions

File tree

‎.claude/settings.json‎

Lines changed: 35 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,37 @@
11
{
2-
"permissions": {
3-
"allow": [
4-
"mcp__github__get_pull_request_files",
5-
"mcp__github__get_pull_request_comments",
6-
"mcp__github__get_pull_request"
7-
],
8-
"deny": [],
9-
"ask": []
10-
}
2+
"env": {
3+
"ENABLE_TOOL_SEARCH": "true",
4+
"CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS": "40000",
5+
"CLAUDE_CODE_DISABLE_AUTO_MEMORY": "0"
6+
},
7+
"enabledPlugins": {
8+
"gh-please@passionfactory": true,
9+
"please@passionfactory": true,
10+
"review@passionfactory": true,
11+
"github@passionfactory": true,
12+
"standards@passionfactory": true,
13+
"dev-tools@passionfactory": true,
14+
"vue@pleaseai": true,
15+
"antfu@pleaseai": true,
16+
"claude-md-management@pleaseai": true,
17+
"vitest@pleaseai": true,
18+
"gatekeeper@pleaseai": true,
19+
"claude-code-setup@claude-plugins-official": true,
20+
"cloudflare@cloudflare": true
21+
},
22+
"extraKnownMarketplaces": {
23+
"passionfactory": {
24+
"source": {
25+
"source": "github",
26+
"repo": "chatbot-pf/engineering-standards"
27+
}
28+
},
29+
"pleaseai": {
30+
"source": {
31+
"source": "github",
32+
"repo": "pleaseai/claude-code-plugins"
33+
}
34+
}
35+
},
36+
"language": "en"
1137
}

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,4 +69,7 @@ typings/
6969
.env
7070

7171
# next.js build output
72-
.next
72+
.next
73+
74+
# please plugin runtime state
75+
.please/state/

‎.please/INDEX.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# .please/ Workspace Index
2+
3+
> Central navigation for all project artifacts managed by the please plugin.
4+
5+
## Project Documents
6+
7+
| Document | Purpose |
8+
|---|---|
9+
| [`../ARCHITECTURE.md`](../ARCHITECTURE.md) | Repository-level bird's-eye view |
10+
| [`../CLAUDE.md`](../CLAUDE.md) | Project-level AI instructions |
11+
12+
## Directory Map
13+
14+
| Path | Purpose |
15+
|---|---|
16+
| `state/` | Runtime session state (progress) — not tracked in git |
17+
| `docs/tracks/` | Implementation tracks (spec + plan) → [Tracks Index](docs/tracks/index.md) |
18+
| `docs/product-specs/` | Product-level specifications → [Product Specs Index](docs/product-specs/index.md) |
19+
| `docs/decisions/` | Architecture Decision Records → [Decisions Index](docs/decisions/index.md) |
20+
| `docs/investigations/` | Bug investigation reports |
21+
| `docs/research/` | Research documents |
22+
| `docs/references/` | External reference materials (-llms.txt etc.) |
23+
| `docs/knowledge/` | Stable project context (product, tech-stack, guidelines) |
24+
| `templates/` | Workflow templates (plugin-provided) |
25+
| `scripts/` | Utility scripts (plugin-provided) |
26+
27+
## Configuration
28+
29+
See [config.yml](config.yml) for workspace settings.
30+
31+
## Workflows
32+
33+
- `/please:new-track` — Create feature specification and architecture plan
34+
- `/please:implement` — TDD implementation from plan file
35+
- `/please:finalize` — Finalize PR, move track to completed

‎.please/config.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
language: en # Output language (ko | en)
2+
3+
# Document path overrides (optional — defaults shown)
4+
docs:
5+
tracks: .please/docs/tracks
6+
product-specs: .please/docs/product-specs
7+
decisions: .please/docs/decisions
8+
investigations: .please/docs/investigations
9+
research: .please/docs/research
10+
references: .please/docs/references
11+
knowledge: .please/docs/knowledge

‎.please/docs/decisions/index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Decisions Index
2+
3+
> Auto-maintained by /please:plan.
4+
5+
| ADR | Title | Date | Status |
6+
|-----|-------|------|--------|

‎.please/docs/knowledge/product-guidelines.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Product Guidelines: Vercel Action
2+
3+
## Code Style
4+
5+
- **ESLint**: Use `@antfu/eslint-config` (flat config) — enforces consistent formatting without Prettier
6+
- **Commit Convention**: Follow `@commitlint/config-conventional` with Husky pre-commit hooks
7+
- **Language**: JavaScript (CommonJS) — maintain consistency with existing codebase
8+
- **Bundling**: All code must be bundled via `@vercel/ncc` into `dist/` for GitHub Actions distribution
9+
10+
## Documentation Style
11+
12+
- Write in clear, concise English
13+
- Use markdown tables for input/output documentation
14+
- Include workflow YAML examples for usage patterns
15+
- Maintain backward compatibility notes in README
16+
17+
## UX Principles
18+
19+
- **Sensible Defaults**: Minimize required inputs; provide reasonable defaults where possible
20+
- **Transparent Feedback**: Always surface deployment URLs and status through PR/commit comments
21+
- **Graceful Degradation**: Handle missing optional inputs without failing the workflow
22+
- **Clear Error Messages**: Provide actionable error messages when deployment or configuration fails
23+
24+
## Versioning & Releases
25+
26+
- Follow semantic versioning
27+
- Use release-please for automated releases
28+
- Maintain major version tags (e.g., `v41`) for GitHub Actions consumers
29+
30+
## Quality Gates
31+
32+
- All changes must pass ESLint (`pnpm lint`)
33+
- All changes must pass tests (`pnpm test`)
34+
- Distribution bundle must be rebuilt (`pnpm build`) and committed for releases

‎.please/docs/knowledge/product.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Product Guide: Vercel Action
2+
3+
## Vision
4+
5+
Provide the most reliable and feature-rich GitHub Action for automating Vercel deployments, giving developers more control than Vercel's native GitHub integration.
6+
7+
## Target Users
8+
9+
- **Development teams** using GitHub Actions for CI/CD who deploy to Vercel
10+
- **Open source maintainers** wanting automated preview deployments on pull requests
11+
- **DevOps engineers** needing fine-grained control over Vercel deployment workflows
12+
13+
## Core Features
14+
15+
1. **Vercel Deployment** — Execute Vercel CLI deployments (preview and production) from GitHub Actions
16+
2. **PR & Commit Comments** — Automatically comment deployment URLs on pull requests and commits
17+
3. **Alias Domains** — Assign custom domains to deployments with template variables (PR number, branch name)
18+
4. **Backward Compatibility** — Maintain support for legacy "zeit-" prefixed inputs
19+
5. **Flexible Configuration** — Support working directories, team scopes, custom CLI arguments, and project name overrides
20+
21+
## Success Metrics
22+
23+
- Deployment success rate and reliability
24+
- GitHub Marketplace adoption (stars, forks, usage)
25+
- Community issue resolution time
26+
- Backward compatibility maintenance across Vercel CLI versions
27+
28+
## Constraints
29+
30+
- Must run on Node.js 20 runtime (GitHub Actions requirement)
31+
- Must bundle all dependencies into `dist/` via ncc for distribution
32+
- Must maintain backward compatibility with deprecated "zeit-" prefixed inputs
33+
- Vercel token and project/org IDs are required inputs

‎.please/docs/knowledge/tech-stack.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Tech Stack: Vercel Action
2+
3+
## Runtime & Language
4+
5+
- **Node.js 22** — Development engine requirement
6+
- **Node.js 20** — GitHub Actions runtime (`runs.using: node20` in action.yml)
7+
- **JavaScript (CommonJS)** — Primary language; single entry point `index.js`
8+
9+
## Package Manager
10+
11+
- **pnpm 10.15.0** — Monorepo with workspace examples in `example/`
12+
13+
## Core Dependencies
14+
15+
| Package | Purpose |
16+
|---|---|
17+
| `@actions/core` | GitHub Actions toolkit (inputs, outputs, logging, secrets) |
18+
| `@actions/exec` | Shell command execution for Vercel CLI |
19+
| `@actions/github` | GitHub API client (Octokit) for PR/commit comments |
20+
| `axios` | HTTP requests for alias domain management |
21+
| `vercel` (v41.1.4) | Vercel CLI — deployment engine |
22+
| `common-tags` | Template literal tag functions for comment formatting |
23+
24+
## Dev Tooling
25+
26+
| Tool | Purpose |
27+
|---|---|
28+
| `@antfu/eslint-config` | ESLint flat config (no Prettier) |
29+
| `jest` | Testing framework |
30+
| `@vercel/ncc` | Single-file bundler for `dist/` distribution |
31+
| `husky` | Git hooks (pre-commit) |
32+
| `@commitlint/cli` + `config-conventional` | Commit message validation |
33+
34+
## CI/CD
35+
36+
- **GitHub Actions** — CI workflows for testing and deployment validation
37+
- **release-please** — Automated semantic versioning and releases
38+
39+
## Build & Distribution
40+
41+
- Source: `index.js` (CommonJS entry point)
42+
- Bundle: `pnpm build` → `@vercel/ncc` → `dist/index.js`
43+
- The `dist/` folder must be committed for GitHub Actions to execute

‎.please/docs/knowledge/workflow.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Project Workflow
2+
3+
> Development workflow conventions for vercel-action.
4+
> Referenced by `/please:implement`.
5+
6+
## Guiding Principles
7+
8+
1. **The Plan is the Source of Truth**: All work is tracked in the track's `plan.md`
9+
2. **The Tech Stack is Deliberate**: Changes to the tech stack must be documented in `tech-stack.md` before implementation
10+
3. **Test-Driven Development**: Write tests before implementing functionality
11+
4. **High Code Coverage**: Aim for >80% code coverage for new code
12+
5. **Non-Interactive & CI-Aware**: Prefer non-interactive commands. Use `CI=true` for watch-mode tools
13+
14+
## Task Workflow
15+
16+
All tasks follow a strict lifecycle within `/please:implement`:
17+
18+
### Standard Task Lifecycle
19+
20+
1. **Select Task**: Choose the next available task from `plan.md`
21+
2. **Mark In Progress**: Update task status from `[ ]` to `[~]`
22+
3. **Write Failing Tests (Red Phase)**:
23+
- Create test file for the feature or bug fix
24+
- Write unit tests defining expected behavior
25+
- Run tests and confirm they fail as expected
26+
4. **Implement to Pass Tests (Green Phase)**:
27+
- Write minimum code to make failing tests pass
28+
- Run test suite and confirm all tests pass
29+
5. **Refactor (Optional)**:
30+
- Improve clarity, remove duplication, enhance performance
31+
- Rerun tests to ensure they still pass
32+
6. **Verify Coverage**: Run coverage reports. Target: >80% for new code
33+
7. **Document Deviations**: If implementation differs from tech stack, update `tech-stack.md` first
34+
8. **Commit**: Stage and commit with conventional commit message
35+
9. **Update Progress**: Mark the task as completed in `## Progress` with a timestamp
36+
37+
### Phase Completion Protocol
38+
39+
Executed when all tasks in a phase are complete:
40+
41+
1. **Verify Test Coverage**: Identify all files changed in the phase, ensure test coverage
42+
2. **Run Full Test Suite**: Execute all tests, debug failures (max 2 fix attempts)
43+
3. **Manual Verification Plan**: Generate step-by-step verification instructions for the user
44+
4. **User Confirmation**: Wait for explicit user approval before proceeding
45+
5. **Create Checkpoint**: Commit with message `chore(checkpoint): complete phase {name}`
46+
6. **Update Plan**: Mark phase as complete in `plan.md`
47+
48+
## Quality Gates
49+
50+
Before marking any task complete:
51+
52+
- [ ] All tests pass
53+
- [ ] Code coverage meets requirements (>80%)
54+
- [ ] Code follows project style guidelines
55+
- [ ] No linting or static analysis errors
56+
- [ ] No security vulnerabilities introduced
57+
- [ ] Documentation updated if needed
58+
59+
## Development Commands
60+
61+
### Setup
62+
63+
```bash
64+
pnpm install
65+
```
66+
67+
### Daily Development
68+
69+
```bash
70+
pnpm start # Run the action locally (node ./index.js)
71+
```
72+
73+
### Testing
74+
75+
```bash
76+
pnpm test # Run Jest tests
77+
pnpm test -- --coverage # Run tests with coverage report
78+
```
79+
80+
### Before Committing
81+
82+
```bash
83+
pnpm run lint # Run ESLint
84+
pnpm run all # Run lint, build, and test in sequence
85+
pnpm run build # Build dist/ with ncc (must commit dist/ for releases)
86+
```
87+
88+
## Testing Requirements
89+
90+
### Unit Testing
91+
92+
- Every module must have corresponding tests
93+
- Mock external dependencies
94+
- Test both success and failure cases
95+
96+
### Integration Testing
97+
98+
- Test complete user flows
99+
- Verify data transactions
100+
- Test authentication and authorization
101+
102+
## Commit Guidelines
103+
104+
Follow the project's commit convention. See `Skill("standards:commit-convention")` for details.
105+
106+
### Types
107+
108+
- `feat`: New feature
109+
- `fix`: Bug fix
110+
- `docs`: Documentation only
111+
- `style`: Formatting changes
112+
- `refactor`: Code change without behavior change
113+
- `test`: Adding or updating tests
114+
- `chore`: Maintenance tasks
115+
116+
## Definition of Done
117+
118+
A task is complete when:
119+
120+
1. All code implemented to specification
121+
2. Unit tests written and passing
122+
3. Code coverage meets project requirements
123+
4. Code passes all configured checks
124+
5. Progress updated in `plan.md`
125+
6. Changes committed with proper message

‎.please/docs/product-specs/index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Product Specs Index
2+
3+
> Auto-maintained by /please:spec --product.
4+
5+
| Spec | Feature | Created | Related Tracks |
6+
|------|---------|---------|----------------|

0 commit comments

Comments
 (0)