mirror of https://github.com/Matysh/houseplan-card synced 2026-09-29 03:09:36 +00:00

Files

T

Cursor AgentandMatysh 99f7c3a4a9 docs: full project audit pack for agents (market, quality, gaps)

Add docs/AUDIT*.md covering competitive landscape (easy-floorplan 11→430★),
implementation quality, functional integrity, and P0–P3 recommendations.
Refresh PRODUCT.md competitor claim and point STATUS watchlist at the pack.

Co-authored-by: Matysh <Matysh@users.noreply.github.com>

2026-08-05 04:56:01 +00:00

3.9 KiB

Raw Blame History

Project audit — index

Audience: future humans and agents. Read this before proposing features, refactors, or go-to-market work. Snapshot date: 2026-08-05. Product version audited: v1.58.0.

Policy: this pack supplements (does not replace) PRODUCT.md, STATUS.md, SCOPE.md, ARCHITECTURE.md, ROADMAP.md. When they disagree on current market numbers, prefer this pack until PRODUCT.md is refreshed.

Pack contents

File	What it answers
`AUDIT-MARKET.md`	Potential, demand shape, competitors, positioning, risks
`AUDIT-QUALITY.md`	Implementation quality, architecture, security, tests, tech debt
`AUDIT-FUNCTIONAL.md`	Feature integrity, systematicity, claim↔code parity, gaps
`AUDIT-RECOMMENDATIONS.md`	Prioritized actions (P0–P3) with rationale

Executive verdict (one screen)

House Plan is a high-craft, scope-disciplined product in a niche that suddenly got a fast-growing peer. Engineering quality (validation, tap security, CI layers, quality-scale honesty, docs discipline) is well above typical HACS cards. The dominant risks are no longer “can we build it?” — they are discoverability, maintainability of a 8.7k-LOC Lit god-object, and losing the GUI-floorplan narrative to easy-floorplan (≈430★ vs our ≈21★ as of 2026-08-05; a month earlier PRODUCT.md listed easy-floorplan at 11★).

Dimension	Grade	One-line
Product mission / scope discipline	A	SCOPE.md is unusually sharp; non-goals held
Feature depth vs mission	A−	Jobs J1–J7 closed; a few polish gaps
Implementation quality (backend)	A−	Strong WS/HTTP/auth/file races; coverage % still todo
Implementation quality (frontend)	B	Pure modules good; card shell is a maintainability bomb
Test strategy	A−	4 layers + smoke policy; human matrix stale
Competitive moat (technical)	A−	Server-side storage + area-bound rooms still unique
Competitive position (market)	C+	Traction lagging the wave; HACS default still queued
Distribution / social proof	C	Demo stand exists; forum/Reddit/GIF still open
Bus factor / docs	B+	Excellent docs; single maintainer

Do not expand into 3D, furniture CAD, vacuum commands, or cloud — SCOPE forbids them and competitors already own parts of that surface. Do close the distribution gap and keep the moat (registry depth, multi-client storage, overlays that feel like a home — not a drawing app).

How agents should use this

Before a feature: check SCOPE.md → then AUDIT-FUNCTIONAL.md gaps → then AUDIT-RECOMMENDATIONS.md priority.
Before a refactor: read AUDIT-QUALITY.md top-10 debt; prefer extracting from houseplan-card.ts, not rewriting working pure modules.
Before go-to-market or README claims: read AUDIT-MARKET.md — star counts and competitor maturity change monthly; re-verify with GitHub API.
After acting on a P0/P1 item: update the relevant AUDIT file’s “Status” line in the same commit (short note + date), and bump STATUS.md watchlist if the project-level state changed.

Method

Read: PRODUCT, STATUS, ARCHITECTURE, ROADMAP, SCOPE, UX-MODES, TESTING, CONTRIBUTING, quality_scale.yaml, manifest, key src/ + custom_components/ modules.
Metrics: wc -l, bundle size, npm/pytest inventory, GitHub API star counts (2026-08-05), hacs/default#9004 state.
Code-quality pass: god-object sizing, auth UI↔API, tap-action model, validation parity, test layer map.
Explicitly not a full security penetration test or coverage measurement.

Market rationale (older): PRODUCT.md — refresh after this audit lands.
Guard rail: SCOPE.md
Current ops snapshot: STATUS.md
Design: ARCHITECTURE.md, CANVAS.md, BACKDROP.md, VACUUM.md, SUN.md

3.9 KiB Raw Blame History Unescape Escape