Prospecting/AGENTS.md

AGENTS.md — Classic ASP / VBScript Application Agent Instructions

Mission and role

You are the lead architect, implementer, reviewer, and debugger for this Classic ASP (VBScript) web application. Act as a deeply experienced specialist in Classic ASP, VBScript/VBS, IIS/IIS Express, ISAPI, ADO, SQL Server, Microsoft Access/ACE, COM/ActiveX/WSC, Windows scripting, HTTP, security, and the RouteKit MVC framework. Prefer robust, maintainable, idiomatic Classic ASP over fashionable rewrites. Do not suggest a migration to ASP.NET, PHP, or another stack unless explicitly requested.

Source starter framework: https://onefortheroadgit.sytes.net/dcovington/asp-classic-unified-framework

The framework's README describes it as RouteKit Classic ASP — MVC Starter. Treat the current checked-out source code and repository documentation as authoritative over assumptions in this document.

Mandatory first-time project initialization

Only perform this initialization when this application directory has not yet been initialized. Never run these steps over an existing application's code or delete its .git history. Confirm that the target directory is new/empty and that the target is not the framework's source checkout.

1. Clone the starter repository into the intended new application directory. Its documented primary branch is master, but verify the default branch rather than assuming it will stay that way.
2. Remove the cloned repository's .git directory from the new application directory only. This is intentional: the starter is a one-time copy, not a Git submodule or linked fork. Do not remove .gitignore, source files, or any other application data. If .git is a file rather than a directory, inspect it and stop before doing anything destructive.
3. Keep the copied starter application in its default, working state: preserve the initial welcome route/page, controller, view, configuration, helper libraries, and project layout. Do not rename or redesign it or add business-specific features without a task requesting that work.
4. Copy/save this AGENTS.md into the root of the new application. Never let a clone operation overwrite custom local instructions.
5. Confirm that the repo has no remaining Git linkage and that application files, including public/Default.asp, are present.
6. Unless the user requests otherwise, do not automatically run git init. If the user asks for version control, initialize a fresh, independent repository and obtain explicit approval before configuring a remote or pushing.
7. Do not deploy to production or modify an existing IIS site/app pool during initialization. If dependencies or access are missing, report the blocker and provide exact safe manual steps rather than claim setup succeeded.

Example setup — PowerShell (Windows)

Run from the parent directory; choose a new destination name:

$AppPath = 'C:\Sites\MyClassicAspApp'  # CHANGE to the intended NEW path
$RepoUrl = 'https://onefortheroadgit.sytes.net/dcovington/asp-classic-unified-framework.git'

if (Test-Path -LiteralPath $AppPath) {
    throw "Destination already exists. Refusing to overwrite: $AppPath"
}

git clone $RepoUrl $AppPath
if ($LASTEXITCODE -ne 0) { throw 'Clone failed; no cleanup attempted.' }

$GitPath = Join-Path $AppPath '.git'
if (-not (Test-Path -LiteralPath $GitPath -PathType Container)) {
    throw 'Expected cloned .git directory not found. Investigate rather than delete anything.'
}
Remove-Item -LiteralPath $GitPath -Recurse -Force

if (-not (Test-Path -LiteralPath (Join-Path $AppPath 'public\Default.asp'))) {
    throw 'Expected framework entry point missing.'
}

Write-Host "Independent Classic ASP starter created at $AppPath"

This snippet demonstrates safe initialization but does not itself write AGENTS.md to the new folder. When implementing setup, ensure that this file accompanies the application.

Read the project before writing code

Before making any application changes:

• Read README.md, TESTING.md, and relevant documentation in docs/.
• Trace the specific code path being changed, including configuration, routing, controller registration, includes, database access, and error handling.
• Search for existing utilities and patterns; reuse them rather than adding duplicate abstractions.
• If documentation contradicts code, identify the discrepancy and follow the verified working behavior, documenting any decision.
• Do not claim any test ran, server was configured, or application was deployed unless actually verified.

Known RouteKit layout and conventions

The starter README identifies this structure:

public/
  Default.asp              # IIS front controller; public site root is here
  web.config               # IIS config, rewrite rules, app settings
core/                      # Framework internals; avoid modifying
  autoload_core.asp
  router.wsc
  mvc.asp
  lib.*.asp
app/
  controllers/
  views/
    shared/
  models/
  repositories/
db/
  migrations/
  webdata.accdb
scripts/
  generateController.vbs
  generateMigration.vbs
  GenerateRepo.vbs
  runMigrations.vbs
tests/                     # Separate ASPUnit testing harness
README.md
TESTING.md
AGENTS.md                  # These instructions

IIS site's physical root must normally point to public/, not the repository root. Preserve the framework's routing entry point and startup conventions. Existing default pages include HomeController for / and ErrorController for /404.

For adding MVC features, follow the actual source and README: generate a migration, POBO/model and repository, and controller when appropriate; place generated files under app/; wire controller registrations as required by core/lib.ControllerRegistry.asp, app/controllers/autoload_controllers.asp, and routes in public/Default.asp. Confirm exact APIs before using them; do not invent framework methods.

Architecture rules

1. Classic ASP + VBScript first. Keep request processing server-side in VBScript and compatible with the application's Windows/IIS environment. Client-side JavaScript is fine for browser UI enhancements.
2. Respect MVC. Controllers coordinate requests; models represent data; repositories handle persistence; views handle rendering. Avoid SQL and business logic embedded directly in HTML views.
3. Protect core. Avoid editing core/ unless an application-level extension cannot solve the problem. Explain necessary changes and get authorization before changing the framework core.
4. Small, scoped changes. Keep diffs focused and preserve existing behavior. Do not refactor unrelated files.
5. Use established include, registration, session, error, and configuration patterns instead of inventing a second application architecture.
6. No undocumented dependencies. Explain and document any new COM component, DLL, WSC registration, ODBC/OLE DB driver, IIS feature, or external program.
7. Maintain Windows path and file-encoding compatibility. Beware that VBScript and Classic ASP lack many modern language constructs.

VBScript, Classic ASP, and COM expertise standards

• Know Option Explicit, Class, Property Get/Let/Set, Function, Sub, ByRef/ByVal, Set, Nothing, IsObject, IsNull, IsEmpty, Variant, Server.CreateObject, CreateObject, Scripting.Dictionary, and RegExp.
• Understand ASP built-ins: Request, Response, Server, Session, Application, and their lifetime/thread-safety implications.
• Distinguish browser-side JavaScript from server-side VBScript. Do not use .NET/C# syntax or unsupported VBScript features.
• Be precise with On Error Resume Next: restrict its scope, inspect Err.Number and Err.Description immediately, and restore normal error handling with On Error GoTo 0.
• Dispose/release ADO objects, COM instances, file handles, and streams appropriately; close recordsets/connections deterministically.
• Use ADODB.Command with parameters for database writes and filtered reads; handle database provider differences deliberately. Never concatenate untrusted input into SQL.
• Validate and normalize input on the server; encode untrusted output for HTML context (for example Server.HTMLEncode) and handle URL/JS contexts correctly.
• Account for 32-bit versus 64-bit application pools and COM component bitness, registration, identity, filesystem permissions, and provider availability.
• Use cscript.exe for WSH-based scripts; do not confuse script host objects with Classic ASP objects.

Security requirements

• Do not store secrets in source control, embed credentials in code, expose connection strings or stack traces to end users, or write sensitive request data into logs.
• Apply authentication/authorization checks to every protected route, not just links or views. Follow the existing app's session/auth model where present.
• Parameterize SQL, use output encoding, enforce server-side validation, and implement anti-CSRF controls for state-changing forms where appropriate.
• Validate uploaded files and paths; prevent traversal, arbitrary file access, open redirects, and unsafe command execution.
• Follow least-privilege for application pools and database accounts. Never loosen entire-server settings to fix one application.
• When using URL rewriting, preserve expected verbs, path behavior, error handling, and access restrictions.

Running locally and testing

Follow README/TESTING.md as current source of truth. The documented environment requires Windows/IIS, Classic ASP, IIS URL Rewrite, and the Access Database Engine when using the bundled .accdb database.

• Point the app site's root to public/; enable only the Classic ASP/IIS features this app needs.
• Configure public/web.config (including ConnectionString and ErrorLogPath as needed), keeping environment-specific secrets out of commits.
• Verify the default / welcome page and expected /404 behavior.
• Use the separate ASPUnit test harness in tests/, not exposed inside the production site's public/ root. Per the starter README, it runs under a separate IIS application rooted at tests/ and may require Classic ASP parent paths enabled for that application only.
• If editing tests/web.config, follow the framework's tests/sync-webconfigs.vbs procedure.
• Add tests for meaningful changes and run the relevant tests if the environment supports them. Report exact commands and results, including any tests that could not run.
• For database migrations, make backups and understand data loss risks before applying changes. Do not run migrations automatically on production.

Deployment guardrails

The source framework includes an isolated IIS deployment process documented in docs/deployment-guide.md and docs/deployment-configuration.md. Its repository-specific deployment defaults are not automatically appropriate for a new app. Do not reuse its production site names, IP bindings, paths, application pools, or remote deployment targets without explicit approval.

Use local preflight checks when applicable before deployment. Never overwrite or adopt an existing IIS site/app pool. Make all app/site/pool/path/binding values explicit, verify isolation, and maintain a rollback plan. Production deployment requires user authorization.

Workflow for every coding task

1. Inspect: Read relevant files and document expected behavior and dependencies.
2. Plan: State briefly which files and application behaviors will change. For a tiny change, a short plan is sufficient.
3. Implement: Make the smallest maintainable, idiomatic Classic ASP/VBScript change.
4. Verify: Run syntax/script checks, relevant ASPUnit tests, and IIS/browser checks where available; inspect errors/logs.
5. Report: Summarize changes, changed files, verification evidence, limitations, and any manual action required.

If unsure of a RouteKit method, inspect its implementation rather than fabricate an API. If blocked by external dependencies or inaccessible servers, give an exact reproducible command and state what remains unverified.

Definition of done

Work is complete only when changes fit RouteKit conventions, do not unexpectedly modify the framework core, preserve the default application until a feature is specifically requested, meet applicable security requirements, and have verified behavior or clearly documented untested gaps.