Core Design
Frontend UI = view & review addness-cli = AI agent / terminal writes
Addness is a goal management OS built for working alongside AI. Goals are managed as a tree. OpenClaw agents use this CLI to record progress in real time.
Two orgs
| Alias | Org name | Purpose |
|---|---|---|
personal |
Hayashi Shunsuke | Personal projects (online course generator, etc.) |
banana |
Banana | Team projects (AI marketing team, external dev, etc.) |
⚠️ ABSOLUTE RULE: Never write to
bananaorg The banana org is a shared team org managed by other members. AI agents must NOT create, update, complete, or delete goals inbananaorg. Read-only access (summary --org banana, etc.) is allowed.
Shortcuts
+work-start— Start work: detect goal → IN_PROGRESS → show context+work-done— Complete work: COMPLETED + progress log + PR record+progress— Record a progress comment+pr— Record PR URL on a goal (API bug workaround)+goal-create— Create a new goal+summary— Check progress summary+context— Get full context of current goal
Standard AI Agent Workflow
1. On work start (required)
# Auto-detect from git branch (branch naming: goal/<UUID>/description)
addness-cli work start
# Direct goal ID
addness-cli work start --goal <GOAL_ID>
# JSON context for programmatic use
addness-cli context --goal <GOAL_ID>
work start does all of:
- Extract GOAL_ID from git branch
- Set goal status to
IN_PROGRESS - Display full context: goal + deliverables + comments + siblings
2. During work (as needed)
addness-cli progress --message "Design done, starting implementation"
addness-cli progress --message "API tests passing" --status IN_PROGRESS
3. On work completion (required)
# Message only
addness-cli work done --message "Implementation complete"
# With PR link
addness-cli work done --message "Implementation complete" --pr https://github.com/org/repo/pull/42
work done does all of:
link progress --status COMPLETED— post completion commentgoal update --status COMPLETED— finalize status- If
--prgiven: record PR URL as comment (workaround for link pr bug)
Full Command Reference
work start
addness-cli work start # Auto-detect from branch
addness-cli work start --goal <ID> # Direct ID
addness-cli work start --org personal # Specify org
work done
addness-cli work done --message "<summary>"
addness-cli work done --message "<summary>" --pr <PR_URL>
addness-cli work done --message "<summary>" --goal <ID> # No-branch environment
progress (intermediate record)
addness-cli progress --message "<progress>"
addness-cli progress --message "<progress>" --status IN_PROGRESS
addness-cli progress --message "<progress>" --goal <ID>
pr (PR record / link pr bug workaround)
addness-cli pr --url <PR_URL>
addness-cli pr --url <PR_URL> --message "<description>"
addness-cli pr --url <PR_URL> --goal <ID>
# Positional argument also works
addness-cli pr https://github.com/org/repo/pull/42
context (full context for AI agent)
addness-cli context # Auto-detect from branch
addness-cli context --goal <ID> # Direct ID
addness-cli context --goal <ID> --json
Output: {goal: {goal, children, comments, deliverables}, siblings: [...]}
summary
addness-cli summary # Current org summary
addness-cli summary --all # Both orgs (personal + banana)
addness-cli summary --org personal
addness-cli summary --org banana
addness-cli summary --all --json # JSON output
Note: completed_actual field is the accurate count (fixes addness bug).
search (with status filter)
addness-cli search "course"
addness-cli search "marketing" --status IN_PROGRESS
addness-cli search "dev" --org banana --json
org management
addness-cli org list # List orgs
addness-cli org current # Current org
addness-cli org personal # Switch to ハヤシシュンスケ org
addness-cli org banana # Switch to バナナ org
addness-cli org switch <UUID> # Switch by UUID
pass-through (raw addness commands)
addness-cli -- goal list --depth 5 --json
addness-cli -- goal create --title "New goal" --parent <ID>
addness-cli -- goal get <ID> --with-deliverable --with-comment --json
addness-cli -- comment create --goal <ID> --body "Comment"
Goal Operations (via pass-through)
Create goal
# Always use --parent (only one root goal per org)
addness-cli -- goal create --title "Title" --parent <PARENT_ID>
addness-cli -- goal create --title "Title" --parent <PARENT_ID> --description "Done condition"
Search / browse goals
addness-cli -- goal list --depth 5 --json
addness-cli -- goal list --status IN_PROGRESS --json
addness-cli -- goal list --assigned-to me --json
addness-cli -- goal get <ID> --with-deliverable --with-comment --json
addness-cli -- goal tree <ID> --json
addness-cli -- goal children <ID> --json
addness-cli -- goal siblings <ID> --json
Status values
| Value | Meaning |
|---|---|
NOT_STARTED |
Not started |
IN_PROGRESS |
In progress |
COMPLETED |
Completed |
CANCELLED |
Cancelled |
Note: Internally COMPLETED is managed as isCompleted: true with status: NONE.
addness-cli work done handles this correctly.
Branch naming convention
goal/<GOAL_ID>/description
Example: goal/26ff19d1-5e3c-461b-b175-b54f36aef3c4/implement-login
- Requires at least one commit in the repository
addness-cli work startauto-extracts GOAL_ID
Known bugs (handled by addness-cli)
| Bug | Symptom | Fix |
|---|---|---|
addness link pr |
Always 400 error | addness-cli pr records as comment instead |
addness summary completed count |
Does not count isCompleted=true |
addness-cli summary corrects with jq |
addness detect-goal |
Fails on empty repos | addness-cli custom implementation |
OpenClaw Agent Instructions
- Always call
addness-cli work startwhen beginning work (context load + status update) - If goal detection fails, use
--goal <ID>directly - Always call
addness-cli work done --message "..."when work completes - When creating a PR, pass
--pr <URL>towork doneor calladdness-cli pr --url <URL>separately - If goal ID unknown:
addness-cli -- goal list --assigned-to me --json - Check full summary:
addness-cli summary --all