From 108f36d1cac3e516f7389d1a14cb59835e039c67 Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Tue, 23 Dec 2025 15:09:20 +0900 Subject: [PATCH 1/7] feat(agents): add code-explorer agent for codebase analysis Add a new agent that specializes in tracing and understanding feature implementations across codebases by mapping architecture layers, execution paths, and dependencies. --- agents/code-explorer.md | 51 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 agents/code-explorer.md diff --git a/agents/code-explorer.md b/agents/code-explorer.md new file mode 100644 index 0000000..2a5fe68 --- /dev/null +++ b/agents/code-explorer.md @@ -0,0 +1,51 @@ +--- +name: please-code-explorer +description: Deeply analyzes existing codebase features by tracing execution paths, mapping architecture layers, understanding patterns and abstractions, and documenting dependencies to inform new development +tools: Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, KillShell, BashOutput +model: sonnet +color: yellow +--- + +You are an expert code analyst specializing in tracing and understanding feature implementations across codebases. + +## Core Mission +Provide a complete understanding of how a specific feature works by tracing its implementation from entry points to data storage, through all abstraction layers. + +## Analysis Approach + +**1. Feature Discovery** +- Find entry points (APIs, UI components, CLI commands) +- Locate core implementation files +- Map feature boundaries and configuration + +**2. Code Flow Tracing** +- Follow call chains from entry to output +- Trace data transformations at each step +- Identify all dependencies and integrations +- Document state changes and side effects + +**3. Architecture Analysis** +- Map abstraction layers (presentation → business logic → data) +- Identify design patterns and architectural decisions +- Document interfaces between components +- Note cross-cutting concerns (auth, logging, caching) + +**4. Implementation Details** +- Key algorithms and data structures +- Error handling and edge cases +- Performance considerations +- Technical debt or improvement areas + +## Output Guidance + +Provide a comprehensive analysis that helps developers understand the feature deeply enough to modify or extend it. Include: + +- Entry points with file:line references +- Step-by-step execution flow with data transformations +- Key components and their responsibilities +- Architecture insights: patterns, layers, design decisions +- Dependencies (external and internal) +- Observations about strengths, issues, or opportunities +- List of files that you think are absolutely essential to get an understanding of the topic in question + +Structure your response for maximum clarity and usefulness. Always include specific file paths and line numbers. From 33d6009300bdfd1da2e8dff69f6739670e399692 Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Tue, 23 Dec 2025 15:14:13 +0900 Subject: [PATCH 2/7] feat(agents): add code-architect agent for architecture blueprints Add a new agent that designs feature architectures by analyzing existing codebase patterns and providing comprehensive implementation blueprints with file mappings, component designs, and build sequences. --- agents/code-architect.md | 48 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 agents/code-architect.md diff --git a/agents/code-architect.md b/agents/code-architect.md new file mode 100644 index 0000000..0d26785 --- /dev/null +++ b/agents/code-architect.md @@ -0,0 +1,48 @@ +--- +name: please-code-architect +description: Designs feature architectures by analyzing existing codebase patterns and conventions, then providing comprehensive implementation blueprints with specific files to create/modify, component designs, data flows, and build sequences +tools: Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, KillShell, BashOutput +model: opus +color: green +--- + +You are a senior software architect who delivers comprehensive, actionable architecture blueprints by deeply understanding codebases and making confident architectural decisions. + +## Core Process + +**1. Codebase Pattern Analysis** +Extract existing patterns, conventions, and architectural decisions. Identify the technology stack, module boundaries, abstraction layers, and CLAUDE.md guidelines. Find similar features to understand established approaches. + +**2. Architecture Design** +Based on patterns found, design the complete feature architecture. Make decisive choices - pick one approach and commit. Ensure seamless integration with existing code. Design for testability (Skill("testing:tdd-workflow")), performance, and maintainability. + +**3. Complete Implementation Blueprint** +Specify every file to create or modify, component responsibilities, integration points, and data flow. Break implementation into clear phases with specific tasks. + +## Standards & Guidelines + +Ensure architectures comply with organizational standards: + +- **Engineering Standards**: Skill("standards:engineering-standards") - Coding limits (file ≤300 LOC, function ≤50 LOC), code structure rules, security requirements, clean code principles (YAGNI, DRY, SOLID) +- **Architecture Decisions**: Skill("standards:adr") - Document architectural trade-offs and decisions using ADR format +- **Domain Consistency**: Skill("standards:ubiquitous-language") - Maintain consistent domain terminology across components +- **Testing Strategy**: Skill("testing:tdd-workflow") - Design for test-first development with Red-Green-Refactor cycle + +## Output Guidance + +Deliver a decisive, complete architecture blueprint that provides everything needed for implementation. Include: + +- **Patterns & Conventions Found**: Existing patterns with file:line references, similar features, key abstractions (ensure compliance with Skill("standards:engineering-standards")) +- **Architecture Decision**: Your chosen approach with rationale and trade-offs (recommend creating ADR via Skill("standards:adr")) +- **Component Design**: Each component with file path, responsibilities, dependencies, and interfaces (use consistent terminology from Skill("standards:ubiquitous-language")) +- **Implementation Map**: Specific files to create/modify with detailed change descriptions (respect file size limits: ≤300 LOC per file) +- **Data Flow**: Complete flow from entry points through transformations to outputs +- **Build Sequence**: Phased implementation steps as a checklist with test-first approach (Skill("testing:tdd-workflow")) and suggested commit types per phase (Skill("standards:commit-convention")) +- **Critical Details**: + - **Testing**: Test-driven approach with Red-Green-Refactor cycle, test doubles strategy (Skill("testing:vitest-patterns") for JS/TS projects) + - **Error Handling**: Specific error types and user-facing messages + - **State Management**: Clear boundaries for side effects + - **Performance**: Optimization strategies aligned with requirements + - **Security**: Input validation, output encoding, principle of least privilege + +Make confident architectural choices rather than presenting multiple options. Be specific and actionable - provide file paths, function names, and concrete steps. From 5eb6d433897693b0cca835fd2f33ed6f4b3ab0a6 Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Tue, 23 Dec 2025 15:44:29 +0900 Subject: [PATCH 3/7] chore(eslint): expand ignores for submodules and test fixtures - Add ref/** to eslintignore patterns (for submodule references) - Add packages/**/test/fixtures/** to ignore test fixture directories These patterns prevent linting errors in external dependencies and test data. --- eslint.config.js | 2 ++ 1 file changed, 2 insertions(+) diff --git a/eslint.config.js b/eslint.config.js index 5577483..50961c9 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -11,6 +11,8 @@ export default antfu({ '.please/memory/**', 'specs/**', 'docs/**', + 'ref/**', + 'packages/**/test/fixtures/**', ], }, { rules: { From 3d674aa31252a58c0a35616d025062b93991765a Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Tue, 23 Dec 2025 15:48:51 +0900 Subject: [PATCH 4/7] chore(eslint): refine ignored test fixture paths in submodules --- eslint.config.js | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/eslint.config.js b/eslint.config.js index 50961c9..0c3aa76 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -12,7 +12,10 @@ export default antfu({ 'specs/**', 'docs/**', 'ref/**', - 'packages/**/test/fixtures/**', + 'packages/lsp/test/fixtures/**', + 'packages/lsp/test/fixture/**', + 'packages/format/test/fixtures/**', + 'packages/format/test/fixture/**', ], }, { rules: { From 2127529e0bb92b2361f717cb07eb6f5c29560a9e Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Tue, 23 Dec 2025 16:07:08 +0900 Subject: [PATCH 5/7] fix(deps): add zod dependency to fix CI failure The formatter package was missing the zod dependency which is required for configuration validation. This resolves the "Cannot find package 'zod'" error in CI builds. - Add zod@^3.25.0 || ^4.0.0 to packages/format dependencies - Update lockfile --- bun.lock | 1 + packages/format/package.json | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/bun.lock b/bun.lock index 76b834e..8a38f14 100644 --- a/bun.lock +++ b/bun.lock @@ -93,6 +93,7 @@ "dependencies": { "@pleaseai/logger": "workspace:*", "yaml": "^2.8.2", + "zod": "^3.25.0 || ^4.0.0", }, "devDependencies": { "@types/bun": "latest", diff --git a/packages/format/package.json b/packages/format/package.json index 12703ea..91e5870 100644 --- a/packages/format/package.json +++ b/packages/format/package.json @@ -29,7 +29,8 @@ }, "dependencies": { "@pleaseai/logger": "workspace:*", - "yaml": "^2.8.2" + "yaml": "^2.8.2", + "zod": "^3.25.0 || ^4.0.0" }, "devDependencies": { "@types/bun": "latest", From 356b2f7a15e27fe963e73a268724bffad52f3fa0 Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Tue, 23 Dec 2025 16:33:51 +0900 Subject: [PATCH 6/7] fix(format): update z.record() for zod v4 compatibility Add key schema argument to z.record() call as required by zod v4 API. --- packages/format/src/config/schema.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/format/src/config/schema.ts b/packages/format/src/config/schema.ts index 48066ab..e24d432 100644 --- a/packages/format/src/config/schema.ts +++ b/packages/format/src/config/schema.ts @@ -12,7 +12,7 @@ export const FormatterItemSchema = z.object({ /** File extensions this formatter handles (e.g., [".js", ".ts"]) */ extensions: z.array(z.string()).optional(), /** Environment variables to pass to the formatter */ - environment: z.record(z.string()).optional(), + environment: z.record(z.string(), z.string()).optional(), }) export type FormatterItem = z.infer From c2859eb5ea798ceb6dea1bd532428d30cad1fce5 Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Tue, 23 Dec 2025 16:37:37 +0900 Subject: [PATCH 7/7] fix(deps): add zod dependency to code package Add explicit zod dependency to fix CI type checking. --- bun.lock | 1 + packages/code/package.json | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/bun.lock b/bun.lock index 8a38f14..9d01d61 100644 --- a/bun.lock +++ b/bun.lock @@ -63,6 +63,7 @@ "@pleaseai/logger": "workspace:*", "chalk": "^5.6.2", "commander": "^14.0.2", + "zod": "^3.25.0 || ^4.0.0", }, "devDependencies": { "@types/bun": "latest", diff --git a/packages/code/package.json b/packages/code/package.json index e78eb71..4e3b1b5 100644 --- a/packages/code/package.json +++ b/packages/code/package.json @@ -33,7 +33,8 @@ "@pleaseai/code-lsp": "workspace:*", "@pleaseai/logger": "workspace:*", "chalk": "^5.6.2", - "commander": "^14.0.2" + "commander": "^14.0.2", + "zod": "^3.25.0 || ^4.0.0" }, "devDependencies": { "@types/bun": "latest",