Skip to content

Commit fac6b23

Browse files
Twinsen81Twinsen81
authored
Merge pull request #1114 from wordpress-mobile/add-agents-md-skill
Add AGENTS.md and /implement skill
2 parents 7c17677 + 72933a3 commit fac6b23

File tree

4 files changed

+339
-0
lines changed

4 files changed

+339
-0
lines changed

‎.agents/skills/implement/SKILL.md‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
---
2+
name: implement
3+
description: "End-to-end implementation workflow: plan, implement, verify, commit, and open a draft PR. Use when asked to implement, fix, build, or work on something."
4+
---
5+
6+
# Implement Workflow
7+
8+
This skill handles the full lifecycle: plan -> implement -> verify -> commit -> draft PR.
9+
10+
## Phase 1: Plan (requires approval)
11+
12+
1. **Understand the request** — Read the issue description, linked context, or user instructions.
13+
2. **Explore the codebase** — Find relevant files, understand existing patterns, read tests.
14+
3. **Create an implementation plan**:
15+
- What files will be modified/created
16+
- What the changes will do
17+
- What edge cases to consider
18+
- What tests to add or update
19+
4. **Present the plan and STOP** — Wait for explicit user approval before proceeding.
20+
21+
Do NOT start coding until the plan is approved. If requirements are ambiguous, ask.
22+
23+
## Phase 2: Implement
24+
25+
Execute the approved plan:
26+
- Follow existing code patterns and conventions in the repo
27+
- Keep changes minimal and focused — don't refactor unrelated code
28+
- Kotlin warnings are treated as errors (`allWarningsAsErrors = true`) — write clean code
29+
- Use `org.wordpress.aztec` package conventions
30+
- **Unit tests**: Add or update tests covering new/changed logic. Follow existing test patterns in the repo. If writing meaningful tests would require disproportionate effort (e.g., complex setup, heavy mocking of framework internals), skip but notify the developer explaining why.
31+
32+
## Phase 3: Verify
33+
34+
Run verification checks and fix any failures. Iterate until all checks pass.
35+
36+
### 3a: Compile
37+
38+
```bash
39+
./gradlew :aztec:assembleRelease :app:assembleDebug
40+
```
41+
42+
If other modules were changed, compile those too:
43+
```bash
44+
./gradlew assembleRelease
45+
```
46+
47+
### 3b: Lint
48+
49+
```bash
50+
./gradlew ktlint
51+
```
52+
53+
- Fix violations — prefer real fixes over suppression
54+
- Only suppress when it's a false positive and document why
55+
56+
### 3c: Unit Tests
57+
58+
```bash
59+
./gradlew :aztec:testRelease
60+
```
61+
62+
Or run specific tests related to the changes:
63+
```bash
64+
./gradlew :aztec:testReleaseUnitTest --tests "org.wordpress.aztec.SpecificTest" --info
65+
```
66+
67+
**Test rules:**
68+
- NEVER weaken or remove assertions to make tests pass
69+
- Don't make unrelated or incorrect changes to production code solely to appease a test. If a test reveals a real issue, fix it properly.
70+
- Tests that pass only by not crashing are invalid — every test needs meaningful assertions
71+
- If a test won't pass after reasonable attempts: stop and ask
72+
73+
### 3d: Fix Errors
74+
75+
If any step fails:
76+
1. Analyze the error
77+
2. Fix the issue
78+
3. Re-run the failing check
79+
4. Repeat until green
80+
81+
## Phase 4: Present Changes (requires approval)
82+
83+
Show a summary of all changes made:
84+
- Files modified/created
85+
- Key behavioral changes
86+
- Test coverage
87+
88+
**STOP and wait for user approval** before committing.
89+
90+
## Phase 5: Commit and Draft PR
91+
92+
Only proceed after explicit approval.
93+
94+
### 5a: Run Final Lint
95+
96+
```bash
97+
./gradlew ktlint
98+
```
99+
100+
Fix any remaining issues.
101+
102+
### 5b: Inspect Changes
103+
104+
```bash
105+
git status
106+
git diff --stat
107+
git diff
108+
```
109+
110+
### 5c: Plan Commits
111+
112+
Review the changes and determine if they should be split into multiple commits:
113+
- Independent logical units = separate commits
114+
- Bug fix + feature = separate commits
115+
- Formatting + logic = separate commits
116+
117+
For **each commit**, prepare:
118+
1. **Commit message**: Imperative summary + brief body
119+
2. **Files**: Paths to stage
120+
3. **Summary**: What and why
121+
122+
**Commit message format** — use direct multi-line strings:
123+
```bash
124+
git commit -m "Imperative summary
125+
126+
- Detail one
127+
- Detail two
128+
"
129+
```
130+
131+
**Rules:**
132+
- NO co-author lines — NEVER add "Co-Authored-By" or AI attribution
133+
- Each commit should be cohesive and buildable
134+
- Use `git add -p` to split mixed concerns if needed
135+
136+
### 5d: Stage and Commit
137+
138+
```bash
139+
git add <specific files>
140+
git commit -m "message"
141+
```
142+
143+
### 5e: Push and Create Draft PR
144+
145+
```bash
146+
# Get the correct remote owner/repo
147+
git remote get-url origin
148+
149+
# Push
150+
git push -u origin HEAD
151+
152+
# Create draft PR
153+
PAGER=cat gh pr create --draft --title "PR title" --body "$(cat <<'EOF'
154+
### Fix
155+
<description>
156+
157+
### Test
158+
1. Step 1
159+
2. Step 2
160+
EOF
161+
)"
162+
```
163+
164+
**PR rules:**
165+
- Title: short, under 70 characters
166+
- Body: follows the repo's PR template format (### Fix, ### Test, ### Review)
167+
- Always create as **draft**
168+
- Return the PR URL when done
169+
170+
## Handling Edge Cases
171+
172+
### Working on an issue with a branch name
173+
If the user mentions an issue with a known branch name:
174+
```bash
175+
git checkout trunk && git pull && git checkout -b <branch-name>
176+
```
177+
178+
### Determining diff base for existing PRs
179+
PRs can be stacked — check the actual base:
180+
```bash
181+
PAGER=cat gh pr view <NUMBER> --json baseRefName
182+
```
183+
184+
### Posting review comments
185+
When reviewing or addressing PR feedback:
186+
```bash
187+
# Create review JSON
188+
printf '%s\n' '{
189+
"event": "COMMENT",
190+
"body": "Review comment",
191+
"comments": [
192+
{"path": "file.kt", "line": 42, "body": "Inline comment"}
193+
]
194+
}' > /tmp/pr_review.json
195+
196+
PAGER=cat gh api repos/{owner}/{repo}/pulls/{number}/reviews --method POST --input /tmp/pr_review.json
197+
```

‎.claude/skills‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../.agents/skills

‎AGENTS.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Instructions
2+
3+
This file provides guidance to coding agents when working with code in this repository.
4+
5+
## General Approach
6+
7+
- Analyze assumptions and provide counterpoints — prioritize truth over agreement.
8+
- Treat me as an expert Android developer. Give overviews, not tutorials.
9+
- Always give an overview of the solution before diving into implementation (unless explicitly asked to implement right away).
10+
- Do not add comments for trivial logic or when the name is descriptive enough.
11+
12+
## Architecture Overview
13+
14+
**AztecEditor-Android** is a rich-text HTML editor library for Android, built on the `EditText` / `Spannable` API.
15+
16+
**Stack**: Kotlin, Android Spannable API, Plugin architecture, Gradle with Kotlin DSL
17+
18+
### Module Structure
19+
20+
```
21+
:app — Demo application
22+
:aztec — Core editor library (main deliverable)
23+
:glide-loader — Image loading via Glide
24+
:picasso-loader — Image loading via Picasso
25+
:wordpress-comments — WordPress comments plugin
26+
:wordpress-shortcodes — WordPress shortcodes plugin
27+
:media-placeholders — Media placeholders with Compose support
28+
```
29+
30+
All plugin/loader modules depend on `:aztec`. Published independently to Automattic S3 Maven (`org.wordpress:aztec`, `org.wordpress.aztec:*`).
31+
32+
### Code Navigation (package: `org.wordpress.aztec`)
33+
34+
| To find... | Look in... |
35+
|---------------------------------|------------------------------------------------------|
36+
| Main editor component | `aztec/.../AztecText.kt` (extends EditText, ~3K LOC) |
37+
| Editor facade / initialization | `aztec/.../Aztec.kt` |
38+
| HTML parsing | `aztec/.../AztecParser.kt`, `AztecTagHandler.kt` |
39+
| Custom spans (visual rendering) | `aztec/.../spans/` (62 files — one per HTML element) |
40+
| Text formatting logic | `aztec/.../formatting/` (Block, Inline, Line, List) |
41+
| Block element handlers | `aztec/.../handlers/` (Heading, List, Quote, etc.) |
42+
| Plugin interfaces | `aztec/.../plugins/` (IAztecPlugin, IToolbarButton) |
43+
| HTML source editor | `aztec/.../source/SourceViewEditText.kt` |
44+
| Text change watchers | `aztec/.../watchers/` (30+ files, API-version buckets)|
45+
| Toolbar | `aztec/.../toolbar/AztecToolbar.kt` |
46+
| Undo/redo | `aztec/.../History.kt` |
47+
| Compose placeholders | `media-placeholders/.../ComposePlaceholder*.kt` |
48+
49+
### Key Architectural Patterns
50+
51+
1. **Span-based rendering** — Each HTML element has a custom `Span` class. Spans carry both visual rendering and semantic meaning. The `Spannable` API is central to everything.
52+
53+
2. **Plugin architecture** — `IAztecPlugin` with sub-interfaces (`IToolbarButton`, `IClipboardPastePlugin`, `IOnDrawPlugin`). Plugins for `html2visual` and `visual2html` conversion pipelines.
54+
55+
3. **Facade pattern** — `Aztec` class provides a builder-like fluent API to wire up editor, toolbar, source view, and plugins.
56+
57+
4. **Handler/Formatter split** — Handlers deal with block element structure (headings, lists, quotes). Formatters apply styling (inline, block, line-block, list, link, indent).
58+
59+
5. **Bidirectional HTML conversion** — HTML string <-> Spannable representation, with plugin hooks at each stage.
60+
61+
6. **Watcher pattern** — Multiple `TextWatcher` implementations with API-version-specific buckets (API 25, 26+) for Samsung/OEM compatibility.
62+
63+
### Common Crash Patterns (from recent PRs)
64+
65+
- `IndexOutOfBoundsException` from span start/end being out of bounds — always clamp to `[0, text.length]`
66+
- `IllegalArgumentException` when span end < span start — validate before applying
67+
- Samsung/custom emoji OEM issues causing unexpected span states
68+
- Thread safety in `AztecAttributes` — operations should be synchronized
69+
70+
## Git Operations (CRITICAL)
71+
- **NEVER commit without explicit permission**
72+
- **NEVER push without explicit permission**
73+
- **NEVER create a PR without explicit permission**
74+
- When asked to "fix" or "update" something, that does NOT imply permission to commit/push
75+
- Always wait for explicit "commit", "push", or "create PR" commands
76+
- Do not create branches, rebase, or modify git history unless explicitly asked
77+
78+
## Build Commands
79+
80+
```bash
81+
# Build and run the demo app
82+
./gradlew :app:installDebug && adb shell am start -n org.wordpress.aztec/org.wordpress.aztec.demo.MainActivity
83+
84+
# Build the demo app (without installing)
85+
./gradlew :app:assembleDebug
86+
87+
# Build the library
88+
./gradlew :aztec:assembleRelease
89+
90+
# Lint (ktlint + Android lint)
91+
./gradlew ktlint
92+
./gradlew lintRelease
93+
94+
# Unit tests (core library)
95+
./gradlew aztec:testRelease
96+
97+
# All unit tests
98+
./gradlew testRelease
99+
100+
# Specific test class
101+
./gradlew :aztec:testReleaseUnitTest --tests "org.wordpress.aztec.AztecParserTest" --info
102+
103+
# Specific test method
104+
./gradlew :aztec:testReleaseUnitTest --tests "org.wordpress.aztec.AztecParserTest.testMethodName" --info
105+
```
106+
107+
### Build Configuration
108+
109+
- All Kotlin warnings are errors (`allWarningsAsErrors = true`)
110+
- Versions are defined in root `build.gradle` — check there for current Kotlin, AGP, SDK, and dependency versions
111+
112+
## GitHub Commands
113+
114+
```bash
115+
PAGER=cat gh pr list
116+
PAGER=cat gh pr view <NUMBER>
117+
PAGER=cat gh pr view <NUMBER> --comments
118+
PAGER=cat gh pr diff <NUMBER>
119+
```
120+
121+
## PR Template
122+
123+
PRs follow this format (from `.github/PULL_REQUEST_TEMPLATE.md`):
124+
```
125+
### Fix
126+
<description of what was fixed/added>
127+
128+
### Test
129+
1. Step 1
130+
2. Step 2
131+
132+
### Review
133+
@reviewer
134+
```
135+
136+
## Skills
137+
138+
| Skill | Trigger phrases |
139+
|-------------|------------------------------------------------------------------------------------------------------|
140+
| `implement` | "implement", "fix this", "work on this", "build this", "add feature", any implementation request |

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

0 commit comments

Comments
 (0)