Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
PlaceOS is a building automation platform.

## Working on this project

This crystal lang library is the API layer, made up of RESP API controllers. Functioning similar to ruby on rails controllers.

Use `crystal tool format` and `./bin/ameba` to format and lint code.
Run specs using `./test` make sure to run specs using a subagent. You can also run individual spec files or use `focus: true` to isolate the spec you're working on. Tests can take some time to run.

Make sure to write thorough tests. Reference existing models in the lib folder if you want to see ORM internals. There are some extentions to the ORM in this project in ./lib/placeos-models/base/* if you need to understand why something isn't working.

Make sure to create and maintain a PLAN.md file to keep track of progress.

## 1. Plan Node Default
- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
- If something goes sideways, STOP and re-plan immediately, don’t keep pushing
- Use plan mode for verification steps, not just building
- Write detailed specs upfront to reduce ambiguity

## 2. Subagent Strategy
- Use subagents liberally to keep main context window clean
- Offload research, exploration, and parallel analysis to subagents
- For complex problems, throw more compute at it via subagents
- One task per subagent for focused execution

## 3. Self-Improvement Loop
- After ANY correction from the user, update `tasks/lessons.md` with the pattern
- Write rules for yourself that prevent the same mistake
- Ruthlessly iterate on these lessons until mistake rate drops
- Review lessons at session start for relevant project

## 4. Verification Before Done
- Never mark a task complete without proving it works
- Diff behavior between main and your changes when relevant
- Ask yourself: "Would a staff engineer approve this?"
- Run tests, check logs, demonstrate correctness

## 5. Demand Elegance (Balanced)
- For non-trivial changes, pause and ask: "Is there a more elegant way?"
- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution"
- Skip this for simple, obvious fixes, don’t over-engineer
- Challenge your own work before presenting it

## 6. Autonomous Bug Fixing
- When given a bug report, don’t ask for hand-holding
- Don’t start by trying to fix it. Instead, start by writing a test that reproduces the bug. Then, have subagents try to fix the bug and prove it by passing that test.
- Point at logs, errors, failing tests, then resolve them
- Zero context switching required from the user

---

## Task Management

1. **Plan First**: Write plan to `tasks/todo.md` with checkable items
2. **Verify Plan**: Check in before starting implementation
3. **Track Progress**: Mark items complete as you go
4. **Explain Changes**: High-level summary at each step
5. **Document Results**: Add review section to `tasks/todo.md`
6. **Capture Lessons**: Update `tasks/lessons.md` after corrections

---

## Core Principles

- **Simplicity First**: Make every change as simple as possible. Impact minimal code.
- **No Laziness**: Find root causes. No temporary fixes. Senior developer standards.
28 changes: 28 additions & 0 deletions OPENAPI_DOC.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10271,6 +10271,7 @@ paths:
callers must have Read on the group
schema:
type: string
format: uuid
nullable: true
- name: subsystem
in: query
Expand Down Expand Up @@ -13872,6 +13873,7 @@ paths:
required: true
schema:
type: string
format: uuid
responses:
200:
description: OK
Expand Down Expand Up @@ -13952,6 +13954,7 @@ paths:
required: true
schema:
type: string
format: uuid
responses:
200:
description: OK
Expand Down Expand Up @@ -14026,6 +14029,7 @@ paths:
required: true
schema:
type: string
format: uuid
responses:
202:
description: Accepted
Expand Down Expand Up @@ -14102,6 +14106,7 @@ paths:
required: true
schema:
type: string
format: uuid
responses:
200:
description: OK
Expand Down Expand Up @@ -14257,6 +14262,7 @@ paths:
in: query
schema:
type: string
format: uuid
nullable: true
- name: limit
in: query
Expand Down Expand Up @@ -14365,6 +14371,7 @@ paths:
required: true
schema:
type: string
format: uuid
responses:
200:
description: OK
Expand Down Expand Up @@ -14442,6 +14449,7 @@ paths:
in: query
schema:
type: string
format: uuid
nullable: true
- name: limit
in: query
Expand Down Expand Up @@ -14630,6 +14638,7 @@ paths:
required: true
schema:
type: string
format: uuid
responses:
200:
description: OK
Expand Down Expand Up @@ -14703,6 +14712,7 @@ paths:
required: true
schema:
type: string
format: uuid
responses:
202:
description: Accepted
Expand Down Expand Up @@ -14777,6 +14787,7 @@ paths:
required: true
schema:
type: string
format: uuid
responses:
200:
description: OK
Expand Down Expand Up @@ -14856,6 +14867,7 @@ paths:
in: query
schema:
type: string
format: uuid
nullable: true
- name: user_id
in: query
Expand Down Expand Up @@ -15048,6 +15060,7 @@ paths:
required: true
schema:
type: string
format: uuid
responses:
200:
description: OK
Expand Down Expand Up @@ -15132,6 +15145,7 @@ paths:
required: true
schema:
type: string
format: uuid
responses:
200:
description: OK
Expand Down Expand Up @@ -15210,6 +15224,7 @@ paths:
required: true
schema:
type: string
format: uuid
responses:
202:
description: Accepted
Expand Down Expand Up @@ -15290,6 +15305,7 @@ paths:
required: true
schema:
type: string
format: uuid
responses:
200:
description: OK
Expand Down Expand Up @@ -15364,6 +15380,7 @@ paths:
in: query
schema:
type: string
format: uuid
nullable: true
- name: zone_id
in: query
Expand Down Expand Up @@ -15551,6 +15568,7 @@ paths:
required: true
schema:
type: string
format: uuid
- name: zone_id
in: path
required: true
Expand Down Expand Up @@ -15635,6 +15653,7 @@ paths:
required: true
schema:
type: string
format: uuid
- name: zone_id
in: path
required: true
Expand Down Expand Up @@ -15713,6 +15732,7 @@ paths:
required: true
schema:
type: string
format: uuid
- name: zone_id
in: path
required: true
Expand Down Expand Up @@ -15793,6 +15813,7 @@ paths:
required: true
schema:
type: string
format: uuid
- name: zone_id
in: path
required: true
Expand Down Expand Up @@ -21127,6 +21148,7 @@ paths:
the group)
schema:
type: string
format: uuid
nullable: true
- name: q
in: query
Expand Down Expand Up @@ -21251,6 +21273,7 @@ paths:
callers)
schema:
type: string
format: uuid
nullable: true
responses:
201:
Expand Down Expand Up @@ -21719,6 +21742,7 @@ paths:
required: true
schema:
type: string
format: uuid
responses:
200:
description: OK
Expand Down Expand Up @@ -21807,6 +21831,7 @@ paths:
on the group)
schema:
type: string
format: uuid
nullable: true
- name: q
in: query
Expand Down Expand Up @@ -21935,6 +21960,7 @@ paths:
callers)
schema:
type: string
format: uuid
nullable: true
responses:
201:
Expand Down Expand Up @@ -22332,6 +22358,7 @@ paths:
required: true
schema:
type: string
format: uuid
responses:
200:
description: OK
Expand Down Expand Up @@ -28039,6 +28066,7 @@ paths:
so callers can drill down.
schema:
type: string
format: uuid
nullable: true
- name: include_children_count
in: query
Expand Down
6 changes: 3 additions & 3 deletions shard.lock
Original file line number Diff line number Diff line change
Expand Up @@ -211,15 +211,15 @@ shards:

placeos-frontend-loader:
git: https://github.com/placeos/frontend-loader.git
version: 2.7.1+git.commit.7a6d8c313b0d4f58fbb9ba71948fe889c6d51ab5
version: 2.7.1+git.commit.a2e3892abaa33f33dbd0918d307e82d1099cea65

placeos-log-backend:
git: https://github.com/place-labs/log-backend.git
version: 0.13.0

placeos-models:
git: https://github.com/placeos/models.git
version: 9.90.0
version: 9.90.1

placeos-resource:
git: https://github.com/place-labs/resource.git
Expand Down Expand Up @@ -267,7 +267,7 @@ shards:

search-ingest:
git: https://github.com/placeos/search-ingest.git
version: 2.11.3+git.commit.fc516c008c9f2116586db762924e79c6fff587a7
version: 2.11.3+git.commit.1a187036e24d2c16fe44e8976c54cb8a417d3139

secrets-env: # Overridden
git: https://github.com/spider-gazelle/secrets-env.git
Expand Down
Loading
Loading