Skip to content

Commit 6d6b80a

Browse files
amondnetamondnet
authored
docs: add ARCHITECTURE.md and initialize .please workspace (#96)
* docs: add ARCHITECTURE.md and initialize .please workspace - Add ARCHITECTURE.md with bird's-eye view of repository structure - Initialize .please/docs/ with knowledge docs (product, tech-stack, workflow, product-guidelines) - Add .please/INDEX.md and track/decision index files - Update .please/config.yml with workspace settings (language, doc path overrides) * docs(architecture): clarify docs/ vs .please/docs/ distinction Add a note explaining that docs/ is for human contributors while .please/docs/ is the AI agent knowledge base for the please-setup plugin.
1 parent 9931a15 commit 6d6b80a

13 files changed

Lines changed: 800 additions & 35 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ jobs:
3131

3232
- name: Setup Bun
3333
uses: oven-sh/setup-bun@v2
34+
with:
35+
bun-version-file: 'package.json'
3436

3537
# ESLint 캐시 복원
3638
- name: Restore ESLint cache
@@ -66,6 +68,8 @@ jobs:
6668

6769
- name: Setup Bun
6870
uses: oven-sh/setup-bun@v2
71+
with:
72+
bun-version-file: 'package.json'
6973

7074
- name: Install dependencies
7175
run: bun install --frozen-lockfile
@@ -89,6 +93,8 @@ jobs:
8993

9094
- name: Setup Bun
9195
uses: oven-sh/setup-bun@v2
96+
with:
97+
bun-version-file: 'package.json'
9298

9399
- name: Install dependencies
94100
run: bun install --frozen-lockfile
@@ -113,7 +119,7 @@ jobs:
113119
- name: Setup Bun
114120
uses: oven-sh/setup-bun@v2
115121
with:
116-
bun-version: '1.2.22'
122+
bun-version-file: 'package.json'
117123

118124
- name: Install dependencies
119125
run: bun install --frozen-lockfile

‎.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: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,15 @@
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
12+
113
review:
214
cubic:
315
enabled: true

‎.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 & Conventions
4+
5+
- **Language**: TypeScript throughout (strict mode)
6+
- **Package manager**: Bun (v1.3.10+)
7+
- **Build system**: Turborepo for monorepo orchestration
8+
- **Linting**: ESLint with @antfu/eslint-config
9+
- **Formatting**: Prettier
10+
- **Commits**: Conventional Commits enforced via commitlint + Husky
11+
- **Node version**: 22.x
12+
13+
## Plugin Standards
14+
15+
- Every plugin must have a `.claude-plugin/plugin.json` manifest
16+
- External plugins are maintained as git submodules in `external-plugins/`
17+
- Built-in plugins live in `plugins/` and are part of the monorepo workspace
18+
- Skills are preferred over SessionStart hooks for token efficiency
19+
- Vendor-synced files (with `SYNC.md` marker) must not be manually edited
20+
21+
## Documentation
22+
23+
- English for all code artifacts: commit messages, PR titles/descriptions, comments
24+
- Each plugin should include a README with installation instructions
25+
- CLAUDE.md serves as the primary AI context document
26+
27+
## Quality Gates
28+
29+
- All PRs require passing CI (lint, typecheck, tests)
30+
- Plugin manifests must pass `claude plugin validate`
31+
- Conventional commit format enforced by pre-commit hook
32+
33+
## Web Marketplace
34+
35+
- Built with Nuxt 4, Vue 3, Nuxt UI v4
36+
- Content managed via Nuxt Content
37+
- Static generation for production deployment

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

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Product Guide: Claude Code Plugins Marketplace
2+
3+
## Vision
4+
5+
A curated, community-driven marketplace of plugins for Claude Code that extends AI-assisted development with specialized tools, slash commands, agents, MCP servers, and hooks.
6+
7+
## Target Users
8+
9+
- **Plugin consumers**: Developers using Claude Code who want to enhance their workflow with specialized tools (security analysis, code review, Firebase, Flutter, etc.)
10+
- **Plugin authors**: Developers creating and distributing Claude Code plugins through the marketplace
11+
- **Marketplace maintainers**: The Passion Factory team managing plugin curation, quality, and distribution
12+
13+
## Core Value Proposition
14+
15+
1. **One-command install**: Users add the marketplace and install plugins with simple `/plugin` commands
16+
2. **Curated quality**: All plugins are reviewed and maintained to ensure compatibility and reliability
17+
3. **Broad ecosystem**: From framework-specific tools (Flutter, Firebase) to general-purpose utilities (security, code review, image generation)
18+
4. **Multi-source architecture**: Supports external plugins (git submodules), built-in plugins, vendor-synced skills, and auto-synced Gemini CLI extensions
19+
20+
## Key Features
21+
22+
- **Plugin Registry**: Central `marketplace.json` managing all available plugins
23+
- **Web Marketplace**: Nuxt-based frontend for browsing and discovering plugins
24+
- **Sync Pipeline**: Automated conversion of Gemini CLI extensions to Claude Code plugins
25+
- **Plugin Development Tools**: Built-in tooling for creating, validating, and testing plugins
26+
27+
## Success Metrics
28+
29+
- Number of available plugins in the marketplace
30+
- Plugin installation count and active usage
31+
- Community contributions (PRs, new plugins)
32+
- Plugin compatibility and stability across Claude Code versions

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

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Tech Stack
2+
3+
## Runtime & Package Manager
4+
5+
- **Node.js** 22.x
6+
- **Bun** 1.3.10+ (package manager & script runner)
7+
8+
## Languages
9+
10+
- **TypeScript** 5.9.x (strict mode)
11+
12+
## Build & Monorepo
13+
14+
- **Turborepo** (task orchestration, caching)
15+
- **Bun workspaces** (`packages/*`, `apps/*`, `plugins/*`)
16+
17+
## Web Application (apps/web/)
18+
19+
- **Nuxt 4** (Vue 3 SSR framework)
20+
- **Vue** 3.5.x + **Vue Router** 5.x
21+
- **Nuxt UI** v4 (component library)
22+
- **Nuxt Content** (markdown content management)
23+
- **better-sqlite3** (local database)
24+
25+
## Testing
26+
27+
- **Vitest** 4.x (unit/integration tests)
28+
29+
## Code Quality
30+
31+
- **ESLint** with `@antfu/eslint-config`
32+
- **Prettier** (formatting)
33+
- **commitlint** + **Husky** (conventional commits)
34+
35+
## Plugin Infrastructure
36+
37+
- **MCP SDK** (`@modelcontextprotocol/sdk`) for plugin servers
38+
- **Git submodules** for external plugin management
39+
- **Custom CLI** (`scripts/cli.ts`) for plugin sync/init workflows

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

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
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
65+
```
66+
67+
### Daily Development
68+
69+
```bash
70+
# Web application
71+
cd apps/web && bun run dev
72+
73+
# Plugin sync
74+
bun run skills:sync
75+
```
76+
77+
### Testing
78+
79+
```bash
80+
# Run all tests via Turborepo
81+
bun run test
82+
83+
# Run project-level tests
84+
bun run test:projects
85+
86+
# Watch mode
87+
bun run test:projects:watch
88+
89+
# Integration tests
90+
bun run test:integration
91+
```
92+
93+
### Before Committing
94+
95+
```bash
96+
# Lint
97+
bun run lint
98+
99+
# Build (includes typecheck)
100+
bun run build
101+
102+
# Validate plugin manifests
103+
claude plugin validate <path-to-plugin-dir>
104+
```
105+
106+
## Testing Requirements
107+
108+
### Unit Testing
109+
110+
- Every module must have corresponding tests
111+
- Mock external dependencies
112+
- Test both success and failure cases
113+
114+
### Integration Testing
115+
116+
- Test complete user flows
117+
- Verify data transactions
118+
- Test authentication and authorization
119+
120+
## Commit Guidelines
121+
122+
Follow the project's commit convention. See `Skill("standards:commit-convention")` for details.
123+
124+
### Types
125+
126+
- `feat`: New feature
127+
- `fix`: Bug fix
128+
- `docs`: Documentation only
129+
- `style`: Formatting changes
130+
- `refactor`: Code change without behavior change
131+
- `test`: Adding or updating tests
132+
- `chore`: Maintenance tasks
133+
134+
## Definition of Done
135+
136+
A task is complete when:
137+
138+
1. All code implemented to specification
139+
2. Unit tests written and passing
140+
3. Code coverage meets project requirements
141+
4. Code passes all configured checks
142+
5. Progress updated in `plan.md`
143+
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+
|------|---------|---------|----------------|

‎.please/docs/tracks/index.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Tracks Index
2+
3+
> Auto-maintained by /please:plan and /please:finalize.
4+
5+
## Active
6+
7+
| Track | Feature | Type | Issue | Started | Status |
8+
|-------|---------|------|-------|---------|--------|
9+
10+
## Recently Completed
11+
12+
| Track | Feature | Type | Issue | Completed | Outcome |
13+
|-------|---------|------|-------|-----------|---------|
14+
15+
## Tech Debt
16+
17+
See [tech-debt-tracker.md](tech-debt-tracker.md).

0 commit comments

Comments
 (0)