Teachers Aid Laravel Package

Technical Evaluation

Architecture fit: v0.3.0 materially improves TAC’s fit for Laravel applications that already have a live catalog. The new read tools (catalog_overview, catalog_search, catalog_get) close a critical gap: the agent can discover IDs before proposing changes, reducing duplicate-create behavior such as creating a second course instead of renaming an existing one. The package still preserves a strong propose-then-apply architecture: tools record proposals, and PlanApplier remains the only writer. This is the right control boundary for a TPM-led rollout.

Integration feasibility: Moderate and improving. The package remains Laravel/config-driven, with entity and relation allowlists. v0.3.0 adds runtime flexibility: TeachersAid::tools(ChangePlan), systemPrompt(), prompt(), TOOL_NAMES, and PrismTools::live() let a host runtime own the tool loop instead of relying entirely on the package driver. That supports both Prism-based and custom orchestration, but increases integration responsibility for plan state, retries, and tool-loop behavior.

Technical risk: v0.3.0 is still a pre-1.0 package and should be treated as beta. Several changes are behaviorally significant:

• Proposal-time validation now refuses invalid fields, missing IDs, reused refs, unresolved $refs, and entities missing from entities. In particular, deployments that omit question from config will now get propose_question refusals rather than recorded-but-unappliable operations. This is a positive safety change but can break existing agent behavior.
• propose_lesson no longer forces content_type: text, so behavior now depends on the column default.
• New attach/detach proposals expand the write surface through teachers-aid.relations; misconfiguration could enlarge blast radius.
• GuardsDeletion defaults to allow-all. That is convenient for development but unacceptable for production without an explicit host policy.
• Read tools increase database/query exposure and require authorization, indexing, and pagination review.

Key questions: What Laravel, PHP, and Prism/harness versions are supported? Is v0.x governed by semver or explicitly unstable? How are pending ChangePlan instances persisted across turns and users? Which entities must be present in entities for existing workflows, especially question? What is the intended production deletion policy? Are read tools scoped to the same authorization boundaries as the host app? How should the UI explain proposal-time “Refused: …” responses to teachers? What is the expected migration path for plans created before v0.3.0?

Integration Approach

Stack fit: Good for Laravel apps using Eloquent models and either Prism or a custom agent runtime. TAC remains configuration-centric: entities controls record-level blast radius, and the new teachers-aid.relations config controls link-level blast radius for attach/detach. This fits a TPM-managed rollout because the allowed scope is explicit and reviewable.

Migration path: Pin v0.3.0 and audit configuration before enabling new capabilities. Add question and any other required entities to entities; define only approved relations in teachers-aid.relations; implement a host GuardsDeletion policy before allowing delete proposals; and regression-test prompts against the new proposal-time validation behavior.

Compatibility: Mostly additive, but not risk-free. The proposal validation change and the question config requirement are the main compatibility concerns. The optional/closure driver is an enabling change, not a breaking one. Existing pending plans should be validated against the new proposal checks before applying. Confirm Composer constraints for Laravel/PHP/Prism rather than assuming compatibility from the release notes.

Sequencing: Start with installation, config audit, and deletion guard implementation. Then wire the runtime and plan persistence, enabling read tools first. Next enable create/update proposals, then attach/detach, and only then enable delete proposals. Finish with prompt regression tests, authorization checks, and observability for refusals, guard vetoes, and apply failures.

Operational Impact

Maintenance: Configuration becomes the primary operational control surface. Entity and relation drift will cause refusals or unexpected inability to apply proposals. TAC should have named owners for config, prompts, deletion guards, and Prism/runtime integration. Pre-1.0 churn should be expected.

Support: Support teams need to distinguish proposal-time refusals from apply-time failures. The new “Refused: …” responses are safer but can confuse users if the UI does not explain why the agent could not record a proposal. Guard vetoes and attach/detach operations need audit trails.

Scaling: Read tools can increase catalog queries, so catalog_search needs indexes, pagination, and sensible limits. Runtime-owned tool loops can increase LLM calls and token usage, especially when validation refusals trigger retries. Plan size across turns and live tool execution volume should be monitored.

Failure modes: Misconfigured entities or relations can block valid operations or widen blast radius. Default allow-all deletion is the highest-risk production gap. Runtime loop ownership can lose or corrupt plan state if not persisted carefully. Proposal-time validation reduces apply-time failures but does not eliminate them, and over-strict configuration can produce repeated model refusals.

Ramp-up: Moderate. Teams must understand propose/apply semantics, ChangePlan, tool names, relation allowlists, and deletion guard behavior. A staged rollout in staging with read-only tools, then non-destructive proposals, then attach/detach, then guarded deletes is appropriate. Production readiness should require an explicit deletion policy, a reviewed relation allowlist, Composer lockfile discipline, and regression prompts for validation-refusal behavior.