Skip to content

Commit 270eca1

Browse files
amondnetamondnet
committed
chore: setup .please/ workspace (v7→v10 migration)
- Add .please/config.yml with project configuration - Add .please/INDEX.md as workspace entry point - Add .please/docs/ structure (tracks, knowledge, decisions, product-specs) - Update .gitignore to exclude .please/state/ (runtime state) - Remove legacy .please/memory/progress.txt (replaced by track system) - Remove agents/ directory (code-architect, code-explorer, librarian moved to plugin system) - Fix trailing comma in .claude/settings.json
1 parent 053b18e commit 270eca1

16 files changed

Lines changed: 353 additions & 460 deletions

File tree

‎.claude/settings.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@
3636
"mcp-dev@pleaseai": true,
3737
"testing@passionfactory": true,
3838
"tidy-first@passionfactory": true,
39-
"vitest@pleaseai": true,
39+
"vitest@pleaseai": true
4040
},
4141
"extraKnownMarketplaces": {
4242
"code-intelligence": {

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,8 @@ coverage/
3636
# Claude settings
3737
/.claude/settings.local.json
3838

39-
# Please memory
39+
# Please runtime state
40+
.please/state/
4041
.please/memory/tasklist.json
4142

4243
# Reference repositories (local checkout only)

‎.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: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
schema_version: 2 # Config schema version (do not edit manually)
2+
3+
language: en # Output language (ko | en)
4+
5+
# GitHub integration (optional)
6+
# github:
7+
# project: 5 # GitHub Project number (from URL: /orgs/{org}/projects/5)
8+
# owner: pleaseai # GitHub org or user owning the project
9+
# issue_required: true # Create GitHub Issue for every track (default: false)
10+
11+
# Document path overrides (optional — defaults shown)
12+
docs:
13+
tracks: .please/docs/tracks
14+
product-specs: .please/docs/product-specs
15+
decisions: .please/docs/decisions
16+
investigations: .please/docs/investigations
17+
research: .please/docs/research
18+
references: .please/docs/references
19+
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: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Product Guidelines
2+
3+
## Code Style
4+
5+
- **Language**: TypeScript (strict mode with `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`)
6+
- **Runtime**: Bun (test runner, package manager, script execution)
7+
- **Linting**: @antfu/eslint-config (lib type, no JSX)
8+
- **Formatting**: Prettier (via Bun)
9+
- **Module system**: ESM only (`verbatimModuleSyntax`)
10+
11+
## Naming Conventions
12+
13+
- Files: `kebab-case.ts` (e.g., `language-server.ts`, `config-loader.ts`)
14+
- Types/Interfaces: `PascalCase` (e.g., `FormatterConfig`, `LspServerDefinition`)
15+
- Functions/Variables: `camelCase`
16+
- Constants: `UPPER_SNAKE_CASE` for true constants, `camelCase` for derived values
17+
- Package names: `@pleaseai/{name}` scope
18+
19+
## Architecture Principles
20+
21+
1. **Provider pattern** — External integrations (JetBrains, LSP servers) are abstracted behind provider interfaces
22+
2. **Config-driven** — Behavior is controlled via `.please/config.json` or `.please/config.yml`, not hardcoded
23+
3. **Monorepo separation** — Each package has a clear responsibility; cross-package imports use workspace dependencies
24+
4. **CLI-first** — All functionality is accessible via CLI; hook mode is a thin wrapper over CLI commands
25+
5. **Graceful degradation** — Missing LSP servers or formatters should warn, not crash
26+
27+
## Documentation
28+
29+
- README in English (primary) with Korean translation (`README.ko.md`)
30+
- CLAUDE.md maintained for AI coding context
31+
- Inline comments only for non-obvious logic
32+
33+
## Testing
34+
35+
- Test runner: Bun test (`bun test`)
36+
- Test files: co-located in `test/` directories within each package
37+
- Fixtures in `test/fixtures/`

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

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Product Guide
2+
3+
## Vision
4+
5+
Code Please is a CLI tool and Claude Code plugin suite that brings **code intelligence** (auto-formatting and LSP diagnostics) directly into AI-assisted coding workflows. The goal is to ensure that AI-generated code meets the same quality standards as human-written code — properly formatted, type-safe, and lint-clean — without manual intervention.
6+
7+
## Target Users
8+
9+
- **AI-assisted developers** using Claude Code, Dora (MCP), or similar AI coding tools
10+
- **Teams adopting AI coding** who need guardrails for code quality
11+
- **IDE power users** who want JetBrains integration with AI workflows via MCP
12+
13+
## Core Value Proposition
14+
15+
1. **Automatic code formatting** — Files are formatted immediately after AI edits via PostToolUse hooks
16+
2. **Real-time LSP diagnostics** — Type errors and lint issues surface as AI writes code, not after
17+
3. **Multi-language support** — TypeScript, Python, Go, Rust, Kotlin, Dart, and 15+ more languages
18+
4. **Zero-config defaults** — Built-in formatters and LSP servers with sensible defaults; opt-in customization via `.please/config.yml`
19+
5. **IDE bridge** — Dora MCP server connects JetBrains IDEs to AI workflows for symbol navigation and diagnostics
20+
21+
## Product Scope
22+
23+
| In Scope | Out of Scope |
24+
|---|---|
25+
| CLI formatting & LSP diagnostics | Full IDE replacement |
26+
| Claude Code hook integration | Non-AI code editing workflows |
27+
| JetBrains MCP bridge (Dora) | VS Code extension (separate project) |
28+
| Plugin architecture for LSP servers | Custom language server development |
29+
| `.please/config.yml` configuration | GUI configuration interface |
30+
31+
## Success Metrics
32+
33+
- Formatting hook runs in < 2s per file
34+
- LSP diagnostics available within 5s of server startup
35+
- Zero false-positive type errors from supported LSP servers
36+
- Plugin installation works with `npm install -g` or `bun add -g`

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

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Tech Stack
2+
3+
## Runtime & Language
4+
5+
| Layer | Technology | Version |
6+
|---|---|---|
7+
| Runtime | Bun | 1.3+ |
8+
| Language | TypeScript | 5.7+ |
9+
| Module System | ESM | `verbatimModuleSyntax` |
10+
11+
## Build & Development
12+
13+
| Tool | Purpose |
14+
|---|---|
15+
| Turbo | Monorepo task orchestration |
16+
| Bun | Package manager, script runner, test runner |
17+
| Husky | Git hooks |
18+
| lint-staged | Pre-commit linting |
19+
20+
## Code Quality
21+
22+
| Tool | Purpose |
23+
|---|---|
24+
| ESLint 9 | Linting (@antfu/eslint-config, lib type) |
25+
| Prettier | Code formatting (via Bun) |
26+
| TypeScript strict | Type checking (exactOptionalPropertyTypes, noUncheckedIndexedAccess) |
27+
| Codecov | Code coverage reporting |
28+
29+
## Protocols & SDKs
30+
31+
| Protocol | Library | Purpose |
32+
|---|---|---|
33+
| MCP | @modelcontextprotocol/sdk 1.12+ | AI tool communication |
34+
| LSP | vscode-jsonrpc, vscode-languageserver-types | Language server protocol |
35+
36+
## Infrastructure
37+
38+
| Component | Technology |
39+
|---|---|
40+
| Package registry | npm (@pleaseai scope) |
41+
| Release management | release-please |
42+
| CI/CD | GitHub Actions |
43+
| Monorepo structure | Bun workspaces (packages/*, apps/*, hooks/scripts) |
44+
45+
## Key Dependencies
46+
47+
- `@modelcontextprotocol/sdk` — MCP server/client implementation
48+
- `vscode-jsonrpc` — JSON-RPC communication for LSP
49+
- `vscode-languageserver-types` — LSP type definitions
50+
- `yaml` — YAML config file parsing

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

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Project Workflow
2+
3+
> Defines the development workflow conventions for the project.
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+
bun install # Install all workspace dependencies
65+
```
66+
67+
### Daily Development
68+
69+
```bash
70+
bun run dev # Development mode with watch (Turbo)
71+
bun run start # Run CLI directly
72+
```
73+
74+
### Testing
75+
76+
```bash
77+
bun run test # Run all tests via Turbo
78+
bun test # Run tests in current package
79+
```
80+
81+
### Type Checking & Linting
82+
83+
```bash
84+
bun run typecheck # TypeScript type checking via Turbo
85+
bun run lint # ESLint check
86+
bun run lint:fix # ESLint auto-fix
87+
```
88+
89+
### Building
90+
91+
```bash
92+
bun run build # Build all packages via Turbo
93+
bun run build:npm # Generate npm distribution packages
94+
```
95+
96+
## Testing Requirements
97+
98+
### Unit Testing
99+
100+
- Every module must have corresponding tests
101+
- Mock external dependencies
102+
- Test both success and failure cases
103+
104+
### Integration Testing
105+
106+
- Test complete user flows
107+
- Verify data transactions
108+
- Test authentication and authorization
109+
110+
## Commit Guidelines
111+
112+
### Types
113+
114+
- `feat`: New feature
115+
- `fix`: Bug fix
116+
- `docs`: Documentation only
117+
- `style`: Formatting changes
118+
- `refactor`: Code change without behavior change
119+
- `test`: Adding or updating tests
120+
- `chore`: Maintenance tasks
121+
122+
## Definition of Done
123+
124+
A task is complete when:
125+
126+
1. All code implemented to specification
127+
2. Unit tests written and passing
128+
3. Code coverage meets project requirements
129+
4. Code passes all configured checks
130+
5. Progress updated in `plan.md`
131+
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)